News for hackers. Stuff that matters.
Re:A Framework for Writing Better Documentation by DanieleProcida on Wednesday February 03, 2021 @06:33AM (#26012701)
I don't disagree about the importance of introductions.

I can't count the number of times I've looked at the home page of documentation for some product and it has felt like stumbling into a teenagers' conversation conducted entirely incomprehensible references, slang and in-jokes.

An introduction needs to say what the thing is, what it does and why someone might want to use it. Usually that can be expressed in a few sentences.

I don't really see it as a mode of documentation in the way that the four components I describe are.

I wouldn't worry too much though. The framework isn't intended as a "do this, all this and nothing but this or you're doing it wrong" final statement on the art of documentation.

It's more a tool for thinking about what you are writing, for whom, and how you can best write it for them. It's to be used however someone finds it useful.

There are no comments on this comment yet.