Good documentation matters

March 04, 2023

Many of us developers are bad at writing documentation in general. We may write some release notes, explain a feature a couple of times to individuals or groups, tell ourselves that whatever we write will be too context-specific, too likely to get out of date soon to be worth spending more energy on, and move on.

Sure, bad documentation can be worse than no documentation. But good documentation matters, a whole lot, and is worth striving for. Good documentation can even be timeless.

Case in point: Apple's human interface guidelines.

I read the HIG before I even started trying to write my first lines of Objective-C. Possibly even before I had a Mac. It was somehow floating around in the periphery of my consciousness even before I read it.

It was one of those things which set Apple computers apart from the rest of the world, by miles.

Here is a document about how we build good apps and things we value in them. No, there is no code in it. No, it has nothing about new API:s. It is all about stuff around your code. It talks about coherency, about caring about your app and its place. It is so good you can apply it to any platform and come out ahead of most. Wow, these people care this much about their platform? They sit down and compile this much advice to developers? And they keep updating it too?

Nobody else cares like this. At work, we have applied things from the HIG to everything from web apps to Java Swing and made things so much better in the process.

The HIG just added a section on writing. It feels perfect. This is the kind of advice, the kind of care that made Apple's platforms the ones which appealed most to me.

I responded to the post I saw about it that the HIG is probably my favourite document from Apple. We developers have complained a lot about the state of Apple's documentation in the last few years. A HIG section on writing feels to me like a reassuring sign the right kind of people with the right kind of care are still out there getting things done. Everything may not be in perfect shape yet, but if we just keep spreading the care, we will get there.

Also, I should care more about the things I write about the things I create.