News for hackers. Stuff that matters.
Re:Blurry rendering of games on Mac by wlesieutre on Thursday August 14, 2025 @07:38PM (#44906999)
I think their bigger problem is there's shit for documentation. You get a big list of function signatures and if you actually want to know how you're supposed to use anything you find the WWDC session from 4 years ago and hope it's still accurate.
Re:Blurry rendering of games on Mac by xcf_seetan on Thursday August 14, 2025 @08:01PM (#44907152)
Somebody told me that the quality of a company is directly proportional to the quality of its documentation...
Re:Blurry rendering of games on Mac by thfuran on Thursday August 14, 2025 @08:30PM (#44907345)
I guess mathworks is one of the best companies ever.
Re:Blurry rendering of games on Mac by makeitdouble on Thursday August 14, 2025 @09:14PM (#44907611)
Boeing's documentation is probably excellent.

In general it is assumed that documentation is the boring part and paying attention to it is a sign of quality. But where do you put people who prefer writing and/or teaching to thinking long and deep about product issues ?

Re:Blurry rendering of games on Mac by serf on Thursday August 14, 2025 @11:03PM (#44908173)
>Boeing's documentation is probably excellent.

it isn't, it's just ISO/NADCAP conforming.

Re:Blurry rendering of games on Mac by unscaled on Thursday August 14, 2025 @10:12PM (#44907893)
Perhaps the biggest issue with the 737 MAX was lack of documentation. Boeing consciously chose to completely omit several new features (most notoriously MCAS) from the pilot manuals in order to make it seems like nothing important was changed that would require retraining 737 NG pilots on a simulator.

In a sense, this is far worse than what most tech companies do since it is a life-and-death issue and Boeing has made a very conscious effort to hide details here, rather than just being lazy.

Re:Blurry rendering of games on Mac by cpgxiii on Thursday August 14, 2025 @11:15PM (#44908247)
One could say that "the point" of MCAS was to be an implementation detail, something that you would often deliberately hide from software documentation so that users don't design around internal details.

There's something of a history of aerospace vendors omitting "implementation details" that end up contributing to serious accidents (e.g. if you get an Airbus far enough out of the normal envelope protections, you lose stall warning), and an equally sordid history of flight and maintenance crews improvising procedures to the observed (rather than designed/specified) behavior of aircraft systems.

Arguably, the single biggest systematic risk in the current pilot training system is that crews overlearn to the implementation details of their training, rather than the actual principles and flight manuals (e.g. training inadvertently training for quick engine shutdowns, when the consequences of shutting down the wrong engine in reality are much more serious).

Re:Blurry rendering of games on Mac by sofixa on Friday August 15, 2025 @02:25AM (#44909202)
> There's something of a history of aerospace vendors omitting "implementation details" that end up contributing to serious accidents (e.g. if you get an Airbus far enough out of the normal envelope protections, you lose stall warning),

And Airbus control laws and protections are well defined and studied by pilots training for them.

Re:Blurry rendering of games on Mac by cpgxiii on Friday August 15, 2025 @03:12PM (#44916356)
They are now, just as MCAS behavior is well-defined and covered in conversion training now. They were not covered as well prior to AF447.
Re:Blurry rendering of games on Mac by reactordev on Thursday August 14, 2025 @09:51PM (#44907782)
You encourage them to blog about it and you aggregate the posts into documentation - somehow. (I'm sure there's people for that, or an AI, or something). They had to explain it when they implemented it - explain it on a post. Confluence. Somewhere.

You're right though.

Re:Blurry rendering of games on Mac by eru on Thursday August 14, 2025 @10:23PM (#44907951)
Tech writer. Google famously employs quite a few of them for internal documentation.
Re:Blurry rendering of games on Mac by jiggawatts on Friday August 15, 2025 @04:46AM (#44910006)
I've read one of the manuals for the 787 management software stack, and it was... beautiful. It read like a novel. I read it twice on the train for the simple pleasure of it.
Re:Blurry rendering of games on Mac by dlivingston on Thursday August 14, 2025 @10:02PM (#44907840)
Microsoft has excellent documentation. So that's one counterexample. :)
Re:Blurry rendering of games on Mac by cosmotic on Thursday August 14, 2025 @10:22PM (#44907944)
It was excellent. It's a mess last time I looked.
Re:Blurry rendering of games on Mac by userbinator on Thursday August 14, 2025 @11:22PM (#44908294)
Their documentation for the very newest stuff contains very obviously AI-generated inaccurate and misleading crap.
Re:Blurry rendering of games on Mac by userbinator on Friday August 15, 2025 @01:25AM (#44908883)
Don't believe me? Go look at it yourself. They've even "edited" the old docs with AI slop.

https://learn.microsoft.com/en-us/windows-hardware/drivers/u...

"The characteristics of the endpoint determine the size of each packet is fixed and determined by the characteristics of the endpoint."

Re:Blurry rendering of games on Mac by noname120 on Friday August 15, 2025 @04:15AM (#44909811)
That sentence was already there _at least_ since Dec 2022, stop seeing AI everywhere.

https://web.archive.org/web/20221214171028/https://learn.mic...

Re:Blurry rendering of games on Mac by userbinator on Friday August 15, 2025 @03:27PM (#44916486)
They were using an automated editing tool before that.
Re:Blurry rendering of games on Mac by noname120 on Friday August 15, 2025 @05:08PM (#44917272)
Moving goalpost + evidence needed
Re:Blurry rendering of games on Mac by WithinReason on Friday August 15, 2025 @02:42AM (#44909279)
If they used AI the sentence would be coherent
Re:Blurry rendering of games on Mac by sofixa on Friday August 15, 2025 @02:27AM (#44909210)
No they don't. Just last week I was looking for something, found a Google result from Microsoft's docs, but opening it resulted in a page saying they're moving docs around, this one isn't being moved, fuck off. No content, no link to the content.
Re:Blurry rendering of games on Mac by rblatz on Friday August 15, 2025 @04:19PM (#44916882)
Most of the time I just get function signatures that are already exposed via intellisense.

Sometimes they actually have examples of how to use it, but most are just Javadoc level, and of minimal use.

Re:Blurry rendering of games on Mac by internetter on Thursday August 14, 2025 @09:55PM (#44907798)
A WWDC session, I might add, with a mildly relevant title and rarely a hyperlink from the relevant documentation, let alone a timestamp.
Re:Blurry rendering of games on Mac by lilyball on Friday August 15, 2025 @04:54PM (#44917143)
But with a full searchable transcript
Re:Blurry rendering of games on Mac by internetter on Sunday August 17, 2025 @04:29PM (#44934686)
Machine generated transcript*
Re:Blurry rendering of games on Mac by grishka on Thursday August 14, 2025 @10:47PM (#44908096)
But if you find anything with the dark-blue "documentation archive" header, then you know it's some good stuff. Though sometimes outdated.
Re:Blurry rendering of games on Mac by trinix912 on Friday August 15, 2025 @03:41AM (#44909620)
We've come from the monstrous Inside Macintosh tomes, to that early OS X documentation (that's now in the documentation archive), to this seemingly programmatically generated from doc comments thing.
Re:Blurry rendering of games on Mac by grishka on Friday August 15, 2025 @06:59AM (#44910824)
Next they'll start generating documentation from code using LLMs...
Re:Blurry rendering of games on Mac by DaiPlusPlus on Friday August 15, 2025 @11:21AM (#44913532)
That's an odd way to spell "AI hallucination"
Re:Blurry rendering of games on Mac by saagarjha on Thursday August 14, 2025 @11:40PM (#44908388)
Most of this stuff uses APIs greater than four years old, so you're probably not getting those videos unless you look at third party rehosts.
Re:Blurry rendering of games on Mac by trinix912 on Friday August 15, 2025 @03:38AM (#44909608)
What's even worse is they used to have great documentation, then for some nonsense reason archived it and replaced it with this wannabe JavaDocs crap with vague function explanations that leave more questions open than they resolve.

They now tell people to watch WWDC videos as if those relatively short videos contained the same amount of information a proper API documentation does.

Re:Blurry rendering of games on Mac by spike021 on Friday August 15, 2025 @03:53AM (#44909683)
honestly i don't see this as Apple-specific but more of a sign of the times. i've seen a few libraries and vendor platforms we use at work with the same style of documentation (really lack thereof).
Re:Blurry rendering of games on Mac by jiggawatts on Friday August 15, 2025 @04:44AM (#44909994)
Microsoft's documentation quality very noticeably fell of a cliff about a decade ago. Now most of their public APIs and SDKs have hundreds of thousands of "documentation" pages that are just the name of the function with spaces added between the words. There might also be a listing of the parameters, which helpfully tells you that "string param1" is called "param1" and takes a string as the data type.
Re:Blurry rendering of games on Mac by spike021 on Friday August 15, 2025 @12:43PM (#44914566)
Yeah, the extreme basics seems to be the trend. We've actually had a lot of trouble due to this exact problem with one particular vendor now. Even repeated requests to improve their documentation are completely ignored or laughed off. it's too bad I don't have the purchasing power otherwise I'd suggest we should find a different vendor.
Re:Blurry rendering of games on Mac by whstl on Friday August 15, 2025 @07:26AM (#44911000)
I can attest to that. I used to freelance doing porting about 10 years ago, and the main way of having a stable event loop for a game on macOS is not really anywhere clear in the documentation, at least not anywhere I could find.

Libraries and SDL, GLFW and Sokol handle this for you, and I had to poke inside them to actually figure out how to get the same performance of other games.

In a nutshell, the trick is simple, you call [NSApplication finishLaunching] and do a while-loop yourself instead of calling [NSApplication run].