25 05 2010

I’ve been writing a lot of documentation around the systems I’ve developed in my current job lately, and it’s struck me that there’s two primary ways of going about documenting systems. Both are strongly tied to the types of users who will be reading it. I’m going to go through both that I’ve came across and demonstrate their benefits and negatives, and situations where either or both are suitable.

Step by Step

There are always plenty of users who have very little time to learn a new system and just want to perform the task it was designed to do. These users want instructions one after the other, preferably with colour screenshots with huge arrows pointing to key areas, describing the precise details required (including stating without “quote marks”). These users want as little interruption as possible, and value their time very highly. These users couldn’t care less that this particular field is needed to simplify report generation, or that it’s a unique identifier for the record they’re entering. Sentences should be short. Concisely stating the purpose of the task.

The Overview

Then there are users who are slightly more liberal with their time, and are committed to not only using a system but also learning how it works. These users value not only their time but the tools at their disposal, and are continually fascinated with process optimisation, wanting to get more from the system they’re using. They are willing to experiment and ask questions and make suggestions. They sometimes even like to read lengthy, verbose descriptions about the drop-down box in the field, the fact it’s a “Choice” data type, and more choices can be added through the “List Settings” and editing the column itself. They are typically edging toward power users, and will play around with a system to see what it can do.

There we have two very distinct types of users and what types of documentation they like to read. I’ve found that when writing documentation, I’ve had to think carefully about the type of user who will be reading it. Step by Step instructions are the “how” to do a system, and the Overview is more the “why it’s done this way”.

There are benefits to both methods. The Step by Step gets use and value out of the system as it has been designed, and arguably (if you have measuring capabilities in place) you can accurately measure the effectiveness of your system on productivity. The Overview method of documenting systems allows your readers to be able to further get value from the system as it was designed, by thinking of ways of extending it to better suit their needs.

If you’re trying to decide which method to use, it may be simpler to just write out both methods. Write a very brief and concise “How-to” for particular task, and also write an addendum about how the system works and why it works. Describe how the system brings about its value in detail for these “Overview-seeking” types.

SharePoint: Year to View of a Calendar with Data List View Web Part Documentation – User Exploration