A Funny Java Flavoured Look at the World

Tuesday, April 11, 2006

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 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


  • I agree to a point with your comments. I am a fast and avid typer who likes to write a lot of detail "just in case". I can't tell you how many times I've written little documentation only to have, without fail, somone come and ask for more detail. I explain it, and again someone else... and it goes on. I say, more detail is better than less. If they read it (and the extra detail is not just some extra crap that does nothing to aide the reader), then they might have learned that much more. If they don't want to read it, they can skip it. That's the beauty of documentation, you can skim, skip, read it all, or read the cliff notes. The reader decides.

    My biggest pet peave with the majority of developers is this mentality of "if you can code, you shouldn't need to read comments/documentation". That's the biggest pile of crap a professional developer can say. If given enough time, a total noob can of course figure out the code. The point of documentation is two fold. Primarily it's to explain what a chunk of code is doing. But what I find more importantly is the time I waste jumping around from call to call, only to go back and try to figure things out. A few lines of comments on every method and a few single line comments within the code itself is a huge time saver when working with someone else's code.. heck, even your own many times.

    The worse thing a good developer can do is to say "I'll go back and comment my code later.. we need to get this out now". WHAT? Come on. Please spare the excuses of why you can't do what you were hired to do. Commenting code should be required, and the more the better. Everyone knows you are never going to be given time to go back, it's such a lame excuse. Even worse, if you do have *some* time to go back, your most likely going to forget what various pieces of code do because of the time since you worked with it, and/or because you have your mind wrapped around other things and MOST developers can't stand to comment/document. I am one of the few that loves to write details. Even with Java and the norm being to give long descriptive variable/method/class names, I tend to write a great deal.

    So I say, be professional... consider future developers, or your own faulty memory when you need to go back, keep in mind that it will help the company more so by speeding up the time spent learning (or relearning) chunks of code by doing it in the early stages while its fresh in your mind.

    Curious, how many actually read what I wrote or skipped to this sentence? Be honest...

    By Anonymous kevin, at Wed Nov 08, 07:02:00 am 2006  

  • Thanks for your comment Kevin, excellent insight.

    I certainly agree with commenting in detail because you will appreciate it later when you come back it. You and other people of course, a well documented piece of code will be a lot easier to understand and you will be quicker understanding it.

    By Blogger Hosky, at Wed Nov 08, 08:51:00 am 2006  

  • Know your audience. Are you writing comments in your code or are you writing an installation doc. for someone who is 1000 miles away or are you writing for an end user?

    By Blogger rigtenzin, at Thu Nov 09, 02:03:00 pm 2006  

  • I forgot to mention, it's a very good article. Thanks for posting the link.

    I especially like the idea of treating acceptance tests as full-fledged requirements and unit tests as detailed design documentation.

    By Blogger rigtenzin, at Thu Nov 09, 02:12:00 pm 2006  

Post a Comment

Links to this post:

Create a Link

<< Home