The Elephant at WWDC

DISCLAIMER: I used to own the entire Inside Macintosh series (when it was only two or three books), so I know how far the great have fallen.

> First, it concentrates on documenting calls within an API by individual function. For a developer who already understands how that sub-system in macOS works, that’s essential. But trying to grok major topics like Attributed Text simply isn’t possible by referring to individual functions within the API. You first need to get your head around how sub-systems are designed and function, the conceptual information which Apple was once so good at providing. Good conceptual documentation is structured and written quite differently from that for classes and functions with an API, as Apple well knows.

It's pretty par for the course, for generated documentation (headerdoc kind of thing). Much of my own documentation is done the same way. I agree. It isn't actually that good for systemic understanding (I use big fat READMEs for that). However, you can do things like use MARK commands and extension blocks to organize the docs. Jazzy, in particular, is good for this. The new Apple doc generator will probably also be good for it.

But Apple's documentation has definitely gone into the skip, and I am glad to see it being addressed. It has reached the level of brand damage; which is usually where they start paying attention.

That said, I completely understand the challenges of keeping documentation current. If we aren't careful, documentation can become a concrete galosh[0].

[0] https://littlegreenviper.com/miscellany/concrete-galoshes/

> In common with almost every other initiative of its kind, this approach assumes that the best people to document macOS are its engineers. Those engineers are often selected at interview by posing them a coding challenge, but have you ever heard of candidates for a software engineering post being selected by or for their ability to document their code?

I once took an iOS class with a woman who wrote a lot of the graphics subsystem documentation for Apple. She was damn impressive (had a Ph.D, but wasn't actually an engineer -she was a writer). Apple hires good people. Unfortunately, I suspect that she may well have retired, by now.

I wrote this comment[1] as a story about an Apple interview that I did, several years ago. It was quite disappointing to encounter their attitude.

[1] https://news.ycombinator.com/item?id=21377358

I've written about my own experience and practice, in regards to documentation[2].

[2] https://littlegreenviper.com/miscellany/leaving-a-legacy/

The way Apple talks about new developer features/systems seem like ads for very exclusive clubs sometimes. "If you are already doing this, you can do it here now and we show you some teases, talk to us if you want to know more".

One example for me is ReplayKit... yes I don't know too much about Audio/Video but the little documentation there is it feels deliberately obfuscated and lacking. Better API level docs would help but it absolutely needs more high level guides and examples. One WWDC talk linked on a page is not enough.

What I've witnessed a couple of times is that there can be tremendous amounts and great documentation if the feature/framework can be broadly marketed. If it's on a marketing pamphlet it gets a lot of attention but as soon as it becomes standard or a bit less desirable the quality and extent of the docs are the first thing to go it seems. Sometimes "better docs" is the marketed feature but as all marketing campaigns go, they seldom leave a lasting impact.

I've actually wondered if a True Hipster (tm) ever thought of starting a company to develop software for vintage Apple hardware emulated by one of the many open source choices available. The thinking here is that such software affords a higher degree of reliability since the platform is totally dead.

The thinking for a long time was that computer software was compute-limited, that all applications were as intensive as video games, audio / video editing, and 3D rendering. In reality, people may pay for innovative interfaces and data formats when they organize their work in a new way. Software could be used in an "offensive" way to take entire industries as interlocking roles within organizations. Each of these roles, save manual labor and janitorial work, benefits from education, and the nature of that education is to develop certain patterns of thought & behavior.

Software could be designed with the educational background of the user in mind. I'm speaking mostly of enterprise software here, but it could be applied to CAD shops, publishing, anyone who has an education and uses a computer. I'm not talking about Mechanical Turk here.

The idea is to take education philosophy as the common software for all education computer-enhanced roles and design software for educated people that exposes stuff like

    - the ideal way to learn the structure of the software data model

    - text and point-and-click data input and output

    - data processing language

Not the parent poster but I can recommend some books

- The Craft of Scientific Writing, Michael Alley

- The Craft of Editing, Michael Alley

- A Guide to Writing as an Engineer, David Beer and David McMurrey

- On Writing Well, William Zinsser

There's also a plethora of stuff on the web, as you might imagine, too much to go into it all, but McMurrey has a website https://www.prismnet.com/~hcexres/textbook/acctoc.html