Learning to Document

You know, for as long as I’ve been consulting, you’d think that documentation would be an easy task, but for me, it’s always come painfully.  This is mostly likely due to the fact that I hate documenting things.  Well I’m learning that often the things that are least interesting to do, are the most important.  Documentation is one of those things (damn! :> ).

Well, that brings me to some of the things that I’ve learned that can really help your documentation.  I thought I’d share some of things today.

1.  Use a lot of screenshots.  It sounds pretty obvious, but pictures really are a worth a 1000 words.  So get yourself a good screen capture program.  I personally use SnagIt, but anything that takes a screenshot, and allows you to add some arrows, text boxes etc will do the trick.

2.  Take things step by step.  If you really want to make sure someone knows how to do something, start at the beginning, and walk them through each little piece.  As soon as skip steps, you can lose your audience, and then your documentation isn’t worth anything.

3.  Use a real example.  Whenever possible, use something in the system that someone can look at.  For example, if it has to do with data, try to use something that is in the system that someone could look at again.  Often, allowing someone to be able to look at the data on their own terms can help solidify the information.  If you can’t, make sure you show your user how to look up your own data.

4.  Set the stage early on.  Start your documentation with a good overview.  Keep in mind that someone could be reading this document (hopefully) 3, 6 or 12 months down the road.  If you don’t explain what you’re doing well enough…  the documentation can quickly get “foggy”, even to you if you don’t do the steps often enough.

5.  A good title.  This little piece of advice might actually get this read.  It doesn’t matter how good the guts of your document are, if you don’t label it appropriately, no one will ever find it.  This includes being able to find it in a file system, like sharepoint, put it in a location that fits, use good directory names, etc.

Those are a couple tidbits that I’ve picked up that are helping my documentation get better.  Don’t get me wrong, I’m far from an expert, but I have been finding that my stuff is making more sense to me lately, so that’s a good start.  ha ha

Thanks for reading,

As always, thanks for reading and don't forget to check out our SAP Service Management Products at my other company JaveLLin Solutions,
Mike