On Apple's Piss-Poor Documentation
I&#x27;ve been a technical writer for ~8 years (3 at a startup, 5 at Gooble). I don&#x27;t know Apple&#x27;s situation but here&#x27;s my guess:<p>&gt; Is the documentation team too small? (Likely.)<p>Documentation is weird because there seems to be widespread agreement among developers about how lacking it is (and conversely I think it&#x27;s safe to say how important it is for job success) yet technical writing is almost always understaffed, no matter what size company you have. Part of it is that it&#x27;s really hard to show a causal link between the docs we create and developer success. I know it seems silly but that&#x27;s why I&#x27;ve been advocating for getting those little &quot;was this page helpful?&quot; links at the bottom of pages, followed by an opportunity to provide freeform feedback. If developers started using those consistently and leaving testimony about how the docs helped them it would be a lot easier to prove the value of docs. This is especially true when you operate at a big, platform-level scale, as is the case on <a href="https:&#x2F;&#x2F;web.dev" rel="nofollow">https:&#x2F;&#x2F;web.dev</a> (what I work on) and these Apple API docs. Pageviews give us a rough idea of the demand for certain ideas but don&#x27;t tell us anything about whether our docs are actually useful.<p>(As an aside, in some situations it&#x27;s easier to justify the technical writing team&#x27;s existence; e.g. your technical writer specifically creates docs in response to support requests and the support team is able to just link customers to the docs rather than re-answering the same question over and over; or you have access to &quot;customer&#x27;s&quot; code and are able to show that they are following the best practices &#x2F; use cases you mention and avoid anti-patterns you warn about)<p>I&#x27;ll leave with a suggestion because I don&#x27;t have a horse in this race. If this situation is so bad; your best option might be to create a community-managed MDN-style resource for the Apple ecosystem. I would suggest focusing it on 1) API reference documentation and 2) examples (MDN puts the examples within the API reference pages, that would probably work here).<p>Another route could be more of what these people are already doing: make a lot of noise until Apple realizes how bad the situation is. I imagine if you can prove that you&#x27;re leaving their platform because the situation is so bad, that might wake them up.<p>(No disrespect to Apple people; I know how tough this situation is; just trying to provide constructive feedback for the broader community)