Lessons for code documentation from product design?

Book sculpture by Daniel Lai, “Kenjio”

Good documentation is hard to do. It's a balancing act: It should be short yet clear. And of course, you don't want to spend too long on it.

I try to keep 2 high-level questions in mind, and write notes as I go which answer these:

1. What should a user of a system / class / method know?

This guides writing of javadoc and higher-level documents.

A "user" here is a developer who will call on the class/method, but won't look inside it. E.g. if you code in Java, then you're probably a user of java.util.List, and their (good quality) javadoc is aimed at you.

This user wants to understand: The purpose of a class/method, the inputs, the outputs/effects. Where it fits in the application's life-cycle.

2. What should a future developer who will edit the code of that system / class / method know?

This second "user" wants a few more details: Design choices & reasons, a summary for complex bits, any dead-ends to avoid. This last -- making notes on dead-ends and misadventures -- is especially useful when you return to old code & wonder why-did-I-do-it-that-way?

At each level, think about the person reading your documentation -- How have they got here? That is, what do they already know, and what might be strange to them? What are they trying to do? What do they need to know to do that (safely & well)?

Essentially, let's take the ethos of user-centred design -- and apply it to documenting code, by thinking of the developer as a form of user, and documentation as a product.