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.
> 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.
Explanations of design intent might be the most underrated kind of documentation. There's so little of that nowadays in general, in any technology. Personally, I blame shortened attention spans, the death of programming books, and the rise of Stack Overflow. I'm not familiar with the Apple ecosystem, is it really worse in this regard than others?
> Explanations of design intent might be the most underrated kind of documentation. There's so little of that nowadays in general, in any technology. Personally, I blame shortened attention spans, the death of programming books, and the rise of Stack Overflow. I'm not familiar with the Apple ecosystem, is it really worse in this regard than others?
I also blame dogmatic misunderstandings that have crystalized around "Agile." Maybe back in the day a some cookbook process specified a lot of useless documentation be created, but many people seem to have thrown the baby out with the bathwater and declared all documentation useless or not worth the effort.
Also some programming books are to blame. IIRC, the book "Clean Code" completely rejects comments because they can get out of sync with the code and therefore be misleading, and "clean code" should be self-documenting. However, all code can ever tell you is what is, it can never tell you why or what was really intended. Also, when you really think about it, method and variable names are comments too, which can get just as out of sync with what's really going on than a comment block.
I completely agree. I never understood the argument of docs getting out of sync. If an organization prioritizes documentation then the comments are just as likely to stay in sync as the variables.
In-line documentation getting out of sync is a purely organizational problem. If documentation is valued by the organization inline documentation won't get out of sync.
It's the easiest to keep in sync. It lives in the code it documents. It's in the same version control repo and the same version of the source building a binary can build the docs. If it ever does get out of sync with the code it's the most straightforward to fix because it's the same process for fixing an issue in the code itself.
Documentation isn't automatically checked. Tests and sample code are a better alternative, since you can configure things to give you a build error if they ever get outdated.
If you are changing some code that has inline documentation it's your responsibility to update it. If that is not your responsibility then it's an organizational failing. Keeping inline documentation up to date and clean should be part of the organization's coding style guidelines.
Tests are not documentation. They only test a very limited "what" or "how" and give no explanation of "why". If it's closed source software and you're only shipping a binary, the tests do not go with the binaries so they're meaningless to third parties. Sample code isn't much better. Without the organizational pressure to keep it in sync with the code it's demoing and "why" explanations it doesn't provide a lot of useful insight for third parties.
Organizational pressure is a scarce resource, it's a waste to spend it on things that you can do with tooling. Keeping tests and sample code up to date involves more than just fixing compilation errors, sure, but the compilation error gets you reading and paying attention to the right piece of material.
Apple's architectural/design intent documentation is sort of hit or miss. The biggest issue (IMHO) with overall architecture documentation is too often it doesn't make it into written documentation. The key insights are sometimes the middle ten minutes of a WWDC keynote or presentation.
If you didn't attend that WWDC session or pour over all the recordings you've missed that particular key concept. So you're then sort of feeling your way around some new technology and making it work but it's not as efficient or elegant as if you had the whole picture.
Because there's so little documentation time and Apple does not (as a rule) do engineering blogs or similar there's not a lot of of opacity into inner workings or designs. From the outside there's a lot more reading of tea leaves than you see for other platforms.
I see. Engineering blogs do fill some of that role in Microsoft’s stacks. This is not completely ideal either. Blog posts are frozen in time, and newer articles tend to only describe the deltas. So to get a current understanding, you also have to puzzle together various bits and pieces. But at the very least, blogs are easily searchable.
While blog posts aren't ideal they're (like you point out) better than nothing. But blogging goes completely against the grain of how Apple operates internally. The WebKit blog is a singular notable exception because that's a highly visible Open Source project. Even the free-form Q&A portions of WWDC sessions are rarely as frank as they should be in terms of usability.
No blogs is fine, that's just the corporate culture, but no blogs and no good up to date architectural documentation is a huge problem. It leads to cargo-cult understanding or complete misunderstandings by outside developers. Hell, it leads to cargo-cult understanding by internal developers.
I don’t think any tool fixes that, as you alluded to.
I think a great example of this is the difference in docs between OSS Python projects.
Most include the auto generated Sphinx (or whatever) docs, with usually just a README level veneer. I quickly end up needing to wander the code. I swear any OAuth2 client library is fated into falling into this.
The great ones include a “quick start”, overall philosophy/architecture, sections on each sub component, common examples of “advanced usage”, and then the generated API docs (and source code). They let you dig deeper as you learn more, and hit more complicated requirements in your project. Click, requests, Flask, etc. are great examples of this to me.
Sphinx and other tools can be leveraged for all of that. But it does have to be written and maintained.
And not having access to the source (internally or externally) kills me for app dependencies. Sometimes I need to look just to understand the doc or see if I’m making a mistake or there’s a bug. Not trying to get into OSS philosophy, just the practical part for me.
Even the official Python docs can stink in places. The subprocess module replaces X, Y, and Z to be “simpler”, but if you want to know the method args, go read the docs on the thing it “replaces.”
I love “native” apps on my mac, and pay for quite a few. But I’d never try to make one. Even XCode is befuddling to me. It’s not an IDE, it’s an opaque RAD that makes me nostalgic for early 90’s Delphi.
The documentation of Delphi was pretty good. We received Delphi (1.0) on a Friday. I took the manuals home for the weekend to study. I started developing on Monday. On Wednesday we had an application with about 10 screens with access to a database and a working interface to a smartcard reader. Though Delphi certainly had its flaws, I still miss it for developing GUI programs.
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.