[chiefalchemist]

> To write documentation, you need 2 things: an understanding of the subject matter, and a high-level understanding of what the readers want to do.

Yes. But this list is incomplete. In fact, it's missing the two essential questions the go into _any_ communication:

1) Who is the audience?

2) What do / don't they already know?

How you explain what they want to do is a direct funtion of you they are and their current knowledge toolbox (if you will).

The vast majority of tech docs suck because too often the sender assumes the receiver is just like them. That is, the sender fails to put themselves aside; fails to put themselves in the shoes of the receiver.

[205guy]

Those are the trees I was talking about. Actually, 1) is subsumed by “what the reader wants to do,” and 2) is unknowable and you’ll write a hard-to-use doc covering all the cases (kinda like the original submission).

In my experience, all software has a purpose. For example, an API is for writing an app that gets and processes info from the server. That’s the big picture. The audience is someone writing that app. If they can’t write apps, it’s not the job of your doc to teach them. Aim the doc at the competent app-writer, give them useful info, and don’t add any fluff. In fact, if you provide a good API doc, it will teach beginners through good form and good examples.