Writing help pages

Posted Oct 17th, 2005 by Rich

I’ve recently written a Content Management System. That part was fairly easy (well maybe not that easy), the hard part comes when I try and write a series of help pages for it. Why should I? I know it works, I know how to use it, and it looks as simple as pie to me!

Obviously anyone else would look at it and go ‘huh?’. I know something is needed, but it isn’t easy trying to write something that will help others. I have to take regular breaks as I find it extremely tiresome. I find this more difficult to do than the coding itself!

Then of course you realise just how much of it needs explaining… the help pages end up being larger than the scripts!

Why can’t everyone just ‘know’ things straight away, would be sooo much easier :-)

Filed under Rants —

3 Responses to: “Writing help pages”

  1. Kate Bolin responds:
    Posted: October 17th, 2005 at 2:19 pm →

    I’ve recently become the lone manual writer in my office, which is a whole level of fun and delight that I…really didn’t want.

    Have a detailed outline, take lots of breaks, and once you have it written down, see how much of it you can reduce into step-by-step guides. And then get someone who has no clue whatsoever about the system to read it.

    And if you’re making online screencaps, consider something like Wink, which’ll make animated images that show people what’s happening.

  2. Rich responds:
    Posted: October 17th, 2005 at 6:22 pm →

    Well I wrote the thing so the detailed outline is in my head… of course I know that isn’t really the way to go, but writing it down would probably be harder for me. Taking breaks, yes I wholeheartedly agree, and I try and take a break as often as possible!

    The art of writing for non techies, is just that, an art. I can put down the basics but find it difficult to really ‘trnaslate’. Luckily my other half is able tot take my basic outline and flesh it out to an acceptable standard.

    Thanks for the link to Wink, looks like an interesting program and although not useful for this particular application might come in useful for another project of mine.

  3. Rich responds:
    Posted: February 27th, 2006 at 12:05 pm →

    Once again I am at a astage where I have to write some help pages.

    Did I say how much I hate doing that?

    I Hate It.

    There said it.

Sorry. Comments are closed.