5 ms·

Honest question because I'm totally ignorant here: can anyone shed some light on the typical roadblocks for large corporations to release documentation like thi

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"?

smallnix 4y ago
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.
TheSpiceIsLife 4y ago
a) commercial in confidence, and b) non-disclosure agreements with partners. Internateral documentation may also need business / developer processes sanitised.
- happymellon 4y ago
  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.
iamgopal 4y ago
Lot of surface for security and legal attack.
pixiemagic 4y ago
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.
mvonballmo 4y ago
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.
johncoltrane 4y ago
Not being required to do it sounds like a good enough reason for not doing something. Large corporation or not.
xenadu02 4y ago
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.
- rodgerd 4y ago
  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.

smallnix 4y ago

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.

TheSpiceIsLife 4y ago

a) commercial in confidence, and b) non-disclosure agreements with partners. Internateral documentation may also need business / developer processes sanitised.

happymellon 4y ago
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.

iamgopal 4y ago

Lot of surface for security and legal attack.

pixiemagic 4y ago

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.

mvonballmo 4y ago

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.

johncoltrane 4y ago

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

xenadu02 4y ago

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.

rodgerd 4y ago
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.