> They should do it, but I doubt it would cost them nothing.

Let's be real here, they just don't want to do it.

The cost of the documentation review would be peanuts.

Apple has just broken capitalism, they're probably 5 years away from rivaling Saudi Aramco in profits:

https://companiesmarketcap.com/most-profitable-companies/

Financial excuses for Apple strategy decisions don't really hold up to scrutiny ;-)

You have to consider the opportunity cost, probably those people engineering time is better placed on M3 gpu drivers. It takes really excepcional and kind people to achieve what they did AND prepare public documentation along the way for the profit of open source community. It sometimes happens, and we have to celebrate that more, but it's not the normal.

Or, you know, they could hire good technical writers for a fraction of the cost and have them work together with developers, just like other companies do?

Devs would have to write just the hairiest parts.

yep that sounds reasonable, no idea why Apple doesn't do that, my wild guess is that there aren't enough technical writers that can understand low level code, or just a company/team culture that doesn't value it.

You speak so blithely, I can see you've never gone through an Apple documentation review...

Speak less blithely yourself, then ;-)

Perhaps, but releasing it even in an unfinished state would massively reduce the duplication-of-effort which is needed for reverse engineering. There are often clues which would take a long time to find when working blind which you can glean even from a few sentences of concrete inside knowledge.

Honest question because I'm totally ignorant here: can anyone shed some light on the typical roadblocks for large corporations to release documentation like this one, other than "it's just easier not to do it"?

I think a big part of it would broadly fall under "legal and privacy concerns", especially since Apple Silicon is proprietary hardware. They need to work out which details about the hardware they might want to keep secret, and make sure the public documentation only contains things they're happy to share to the public. They then need to make sure it's up to their standards for externally published documents, it probably has to go through a review process, be published under a certain license which needs to be written or selected, and so on and so on.

Documentation for internal consumption often makes assumptions that no longer hold outside of the company. It might reference internal machines or drives that will not be available. It might take shortcuts that will be confusing enough that it will be worse than having no documentation at all. It might just be a few bullet points that refer to asking the right person internally.

If you've ever taken over a department at a company, and inherited the documentation, you've experienced this. It's sometimes better to just reverse-engineer the current state of things than to try to use outdated or misleading or very sparse documentation. Documenting the current state cleanly takes time, effort, and capability. It's an ongoing effort that requires budget and capacity.

And, most of all, it requires that the company see the need of having a good knowledge base, despite such a thing being a short-term cost that only pays out in the long term, and then, in ways that you won't be able to ascribe to one department's budget or another. Corporate structures can get in the way of cross-cutting/long-term benefits.

References to internal concepts (acronyms), Hyperlinks to internal knowledge bases, insight into individual contributers & team / org composition and mention of undisclosed efforts / strategy. And undisclosed failures on whatever level that stakeholders maybe should not see.

Once documented anything becomes public API that customers will expect to work forever with no regressions no matter how many caveats and warnings you put on it.

This is always going to be the biggest barrier, even if there were no concerns around e.g. third-party IP, sanitisation, etc. Apple don't want to end up implicitly committing to supporting every element of the current M1 hardware forever.

Lot of surface for security and legal attack.

Not being required to do it sounds like a good enough reason for not doing something. Large corporation or not.

a) commercial in confidence, and b) non-disclosure agreements with partners.

Internateral documentation may also need business / developer processes sanitised.

Its one thing to write for your team

> This is a huge clusterfuck that requires A to be set before you can use B because of no good reason. :poo:

And another to publicly publish that an API is a turd because you outsourced it for time to market reasons.

Apple is a company with ~$200 billion in liquid cash. If they can't spend $20,000 reworking some spec sheets for the community, what the hell are we paying them for?

FOSS is like the exact opposite of apple. Anyone who has been paying Apple with the expectation that they're suddenly going to play well with others instead of locking everything down as much as they can is delusional.