3 ms·

This post (while not wrong that the docs lack in a lot of areas) is written with apparent ignorance of how documentation is generated and published at Apple. R

This post (while not wrong that the docs lack in a lot of areas) is written with apparent ignorance of how documentation is generated and published at Apple. Right now creating the code and docs are mostly decoupled. Having worked in the department where the docs are made, a tool like DocC is going to let the engineers who work on the code provide better docs to the Devpubs department so the authors there can stop writing things engineers should be writing (since they know it better) and get back to writing the higher level conceptual stuff that requires skill with technical communication that engineers may lack. They’re a small but mighty team that’s constantly overwhelmed, so I look forward to seeing how DocC can help them out and produce more docs.

cratermoon 5y ago
If giving Apple developers tools that automatically generate useful API reference documents frees up the devpubs team to generate the other kinds of documents necessary, I'm all for it. If there's nothing but the API documents, DocC won't really address the issues. > They’re a small but mighty team that’s constantly overwhelmed Perhaps Apple needs to spend some money and effort there, but that sounds like a management problem.
BossingAround 5y ago
> They’re a small but mighty team that’s constantly overwhelmed I think this is an incredibly common situation. Personally speaking, I find that to be an excuse. If a woefully understaffed team of tech writers got the budget for 15 new tech writers, that usually wouldn't solve the problem. The main issue is developers who don't believe documentation is highly important. The "we generate documentation, so we're covered" is exactly the attitude I'd describe as highly unproductive. Of course that's great, but auto-generated docs are a small part of what should be your overall documentation suite. It shouldn't become the developers' excuse for not spending more time on documentation. Tech writers will very rarely write docs from zero. I wouldn't even be surprised if the tech writers at Apple had no access to the source code, in which case they can't possibly write the docs from zero.
Apocryphon 5y ago
Many teams at Apple are small but mighty and constantly overwhelmed. It speaks to the priorities of management to engender the existence of these situations. Or the sclerosis of the company culture.
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.

cratermoon 5y ago

If giving Apple developers tools that automatically generate useful API reference documents frees up the devpubs team to generate the other kinds of documents necessary, I'm all for it. If there's nothing but the API documents, DocC won't really address the issues. > They’re a small but mighty team that’s constantly overwhelmed Perhaps Apple needs to spend some money and effort there, but that sounds like a management problem.

BossingAround 5y ago

> They’re a small but mighty team that’s constantly overwhelmed I think this is an incredibly common situation. Personally speaking, I find that to be an excuse. If a woefully understaffed team of tech writers got the budget for 15 new tech writers, that usually wouldn't solve the problem. The main issue is developers who don't believe documentation is highly important. The "we generate documentation, so we're covered" is exactly the attitude I'd describe as highly unproductive. Of course that's great, but auto-generated docs are a small part of what should be your overall documentation suite. It shouldn't become the developers' excuse for not spending more time on documentation. Tech writers will very rarely write docs from zero. I wouldn't even be surprised if the tech writers at Apple had no access to the source code, in which case they can't possibly write the docs from zero.

Apocryphon 5y ago

Many teams at Apple are small but mighty and constantly overwhelmed. It speaks to the priorities of management to engender the existence of these situations. Or the sclerosis of the company culture.

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.