A Tip on Writing Software Documentation - don't waste to much time on it

I recently had to write some documentation for a piece of software I wrote for a customer and I did start to find it a hard slog. I think half of the problem was wasn't sure if I was going into too much detail. Then today I read this article by Scott W. Ambler

The TAGRI (They Aren't Gonna Read It) Principle of Software Development

The document makes interesting points like who is actually going to be reading this documentation, who is the target audience? I particucarly liked this point

"Write agile documentation. There are many reasons to write documentation, some good and some bad, and my advice is that any documentation that you do write should be just good enough for your current situation. Extraneous documentation simply won't be read, and even if it is you're wasting the time of the reader. "

If I think about how I use software documentation, I usually try to read the smallest amount of documentation possible and then bash about with the software only going back to the the documentation when if I become stuck or want to use some of the more advanced features.

Taking setting up and writing a blog as an example. The blog practically sets itself up and you can start using it straight away. I only started reading documentation when I wanted to add a site feed or page counter

Although I state I don't like writing documentation, on reading that back to myself I thought, who does like writing documentation! The point of this post is, I want to get into the habit of

writing just enough documentation, no more and no less


if you like this blog check out my other blog Amusing IT Stories which is a blog about yes you have guessed it Amusing IT Stories