2 ms·
While I haven't worked at Apple, I've worked in technical documentation at other places (and still am) and worked with engineers, and I can't help but push back
by chipotle_coyote 5y ago
While I haven't worked at Apple, I've worked in technical documentation at other places (and still am) and worked with engineers, and I can't help but push back a bit on your implicit assertion that better tooling for engineers is going to help Apple make better documentation. Having coding and docs be so decoupled that you're not able to make good documentation is not a tooling problem -- it's an internal communication problem.
From what I can see and what others have mentioned, DocC is an Apple-blessed version of existing community tools like Jazzy. Apple could have been using that already, and indeed the engineers could have been using any number of docs-in-comments systems to generate basic API docs that could have been then forwarded to the docs team.
But even if they didn't have that, it is still up to the engineers to get that information to the docs team somehow, and still up to the docs team to ensure that new APIs and frameworks are documented. Full stop. Someone, probably a PM somewhere, should have the responsibility to make sure those things happen in tandem. For example, new features and new frameworks could go in a issue tracking system, those issues have descriptions from engineers of at least the barebones basics, the docs team has access to those issues, and separate documentation issues are created and linked to those issues. And lack of basic documentation should arguably be treated as a release blocker. I am sure there are a lot of engineers in the audience raising their hands in protest at that, but when you're talking about an API or an SDK, the documentation is essentially your user interface. You don't need to have the equivalent of the multi-volume Inside Macintosh documentation ready to go on shipping day, but you need to have a basic Jazzy/Javadoc-style reference and an overview doc on day one.
I don't doubt Apple's documentation team is "small but mighty," but there seems to be something fundamentally broken in Apple's process. If DocC helps, that's great, but at best it's just a start.