The Elephant at WWDC

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.

> To this day, I have no idea what 'powerd' is, for instance.

You're in luck, there's an extremely helpful and well written man page on exactly that subject. I will quote in its entirety:

"NAME

     powerd -- Daemon that manages Energy Preferences.

SYNOPSIS

     powerd is a launchd managed daemon.

DESCRIPTION

     powerd is a launchd managed daemon."

It still is the case, and the documentation itself has improved greatly over time. PHP is one of the few programming languages that I feel can be used using only the official documentation (with the comments, of course)

My latest one was the documentation for slicing up strings. All the example code for string.prefix() string.suffix() string.subscript() has code examples using arrays.

https://developer.apple.com/documentation/swift/string/28948...

From my perspective, I was in SWE at Apple for over a decade, their documentation started going downhill as iOS development ramped up. By the time they got to the yearly release cycle for macOS and iOS documentation was an afterthought. Most was generated with doxygen from inline docstrings.

The reason I think the quality and quantity dropped was the internal schedules barely (or don't) leave enough time for the engineering work so there's very little time available for high level documentation. Internally tons of "documentation" existed as Radar comments or exchanges on internal mailing lists. Maybe a group's wiki had some crystallized documentation or high level architectural descriptions but good luck accessing it from outside that org. My favorite was some discussion about overall design or architecture that got the "let's take this offline" where all the helpful details ended up shared in an in-person meeting.

The internal secrecy and rapid development pace made it really difficult to get good overviews of technologies internally. I really sympathize with outside developers trying to cobble together an understanding of something where the documentation sucks or is missing.

The DocC tooling isn't going to be anymore effective than doxygen or other auto generated documentation without good architectural documentation. A function definition is nice but knowing you need to decombulate a frobnob before snizzlizing or that decombulation can only safely be done on the main thread is often more important. I can read a function signature but I can't necessarily know all the keys that go into some configuration NSDict passed into it.

I hope the situation improves if the DocC tooling lowers the friction for writing documentation. It sucks having to mix a WWDC presentation, sample code, and iffy docs into a semblance of usable architectural documentation.