The inverted pyramid

The inverted pyramid is how journalists are taught to write typical news stories. It puts the most newsworthy information at the top, and then the remaining information follows in order of importance, with the least important at the bottom. (The quote is from Chip Scanlan.)

This is the right way to write most API documentation.

API documentation users often don't have time and patience to read very much, and don't have the mental capacity to remember everything. There's too much to read and remember, we need to look things up, so the documentation has to get to the point. Directly.

Wikipedia quotes a good example of the inverted pyramid. Notice how there's hardly any buildup: As a reader, you don't need to remember anything before you reach the goal.

Sometimes, API documentation starts with rationales, justification, requirements descriptions or whatnot, and then builds the API description on top of that fundament. Which sounds very logical, but IMO logic is less important than readability. A programmer who has to follow logical reasoning in order to look something up is a programmar who has to forget the intricate details of his/her own programming.

Some examples: A short and a longer example of maintainer documentation. These were written quickly, and a reader can consult the author and the code if the documentation won't do. Library examples of short and longer documentation. These have to be longer and more thorough, since the reader can't ask the author and shouldn't look at the source.

There is also another reason why the inverted pyramid is the right way: it's easy to write. The pyramid style doesn't strain the grey matter. Explain the gist, and the first sentence is done. Elaborate a little, and the first paragraph is done, and the writer's block is done for, too.