Blogging – the joy of lazy documentation

Documentation is something every organisation should do, but not to excess.

Whether it be an online user guide for a piece of software, or an employee guide for a pensions scheme, there are typically two problems:

  • Most people won’t read it
  • You have to keep it up to date anyway

And, often, keeping it up to date is much more hassle than creating it in the first place. It certainly feels like it, anyway, because when you’re fixing an old document you don’t have the satisfaction that comes from creating something new.

So my philosophy has generally been that you should have as little documentation as possible (and no less). The more you have, the harder it is to maintain, and incorrect documentation is usually worse than no documentation at all.

It struck me recently, though, that there is a rather wonderful aspect to blogs in this regard. The great thing about a blog entry is that it has a date prominently displayed on it. Why is this relevant? Because it’s immediately obvious when a posting may be out of date. You never have to go back and maintain your old blog entries, or check that things you said in the past are still correct. It’s understood that they’re perishable goods and may have an expiry date.

So if you want a low-maintenance website, perhaps the best model is to put the absolute basics as static pages and cast as much of it as possible as a blog. You may need to make special provisions for those who visit and need to find something – like having a good search facility, and referring back regularly to past posts which are still important – but in general, the more you can put in blog format, the more interesting your site will be, and the easier your maintenance task.

2 Comments

Yes, I think you are right, Quentin, in that now when an organisation decides upon having a website, a blog should be uppermost in their thoughts. On the online documentation front, a wiki can sometimes be a better option, especially where cost is at a premium and getting the users to help out is an imperative.

Along with a forum for support, blogs and wikis are vital.

Got Something To Say:

Your email address will not be published. Required fields are marked *

To create code blocks or other preformatted text, indent by four spaces:

    This will be displayed in a monospaced font. The first four 
    spaces will be stripped off, but all other whitespace
    will be preserved.
    
    Markdown is turned off in code blocks:
     [This is not a link](http://example.com)

To create not a block, but an inline code span, use backticks:

Here is some inline `code`.

For more help see http://daringfireball.net/projects/markdown/syntax

*

© Copyright Quentin Stafford-Fraser