3 ms·
I'd love to understand WHY Apple's documentation is so notoriously weak. One guess: maybe it's related to their culture of internal secrecy? If a team works on
by simonw 3y ago
I'd love to understand WHY Apple's documentation is so notoriously weak.
One guess: maybe it's related to their culture of internal secrecy? If a team works on a project for years without anyone outside of that team having any visibility of it, writing comprehensive documentation is presumably a lot less valuable - at least while it's under development.
- jitl 3y agoIt’s gotten worse over the years. The new Swift stuff tends to be cursory, but I frequently hit “archived” legacy docs that are super well written and go in depth on whole systems (although it’s now 10 years out of date). My favorite bit of technical writing is the old text system docs: https://developer.apple.com/library/archive/documentation/TextFonts/Conceptual/CocoaTextArchitecture/Introduction/Introduction.html#//apple_ref/doc/uid/TP40009459 https://developer.apple.com/library/archive/documentation/Te... My hypothesis is that in the old days, technical writers on teams would lead the docs effort, but today’s culture may have many teams with only developers, and those developers are primarily interested in shipping code, not docs.
- mschuster91 3y ago> My hypothesis is that in the old days, technical writers on teams would lead the docs effort, but today’s culture may have many teams with only developers, and those developers are primarily interested in shipping code, not docs. And writing good documentation involves a fair bit of QA and remediation effort as well - you don't want your consumers to yell at clouds "why is the stuff in the official documentation not working", so the writers should actually go and test stuff themselves to see if the docs are actually still valid. This is what permanently burned my relations with Openstack - half the stuff in the docs was broken when I tried it, either from old age or never being tested out of Redhat.
- shp0ngle 3y agoIn the old days, they needed to convince people to work on Apple-specific APIs. Mac OS X was miniscule (smaller than today), iOS was either new or didn't even exist. Nowadays, folks have to develop for iOS whether they like it or not, and macOS is on the backburner.