2 ms·
It’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 dep
by jitl 3y ago
It’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.