Technically Speaking

It goes without saying that users within an organization are up near the top in the heap of priorities for the IT department and thereby the IT Manager, this is especially true when documentation for users is considered.

User manuals or procedure documents should be put together in such a way that the user of the application or process regardless of skill level can follow them. This is not meant to say that all documentation is required to be user friendly, but if there is any chance an end user will need or benefit from a document, it should meet their needs and serve to help them.

When creating internal IT department documentation, or working with your team to do so, there is probably a great liklihood that the document can be a good deal more technical. For example, the IT department probably has at least some understanding of what DNS is and how it is used. Users do not likely have this knowledge nor do they want it.

When describing DNS to an end user, I will usually start with the street address analogy which goes something like this:

“DNS is a lookup mechanism that helps a computer find other computers on the Internet. It works similarly to finding a street address.

A DNS Address looks like this: abc.def.ghi.jkl

A street address looks like this: 123 Any Street, Anytown USA

The DNS octet furthest to the right (jkl) represents the host machine much like 123 represents the house number in the street address above. The next group to the left (ghi) would be a designation for the network segment which is similar to the street in the address.”

This type of documentation may seem very simple, and in many cases oversimplified, but the idea is to provide as much information to the user reading the document as possible. This will help them understand the procedure or technology and should lead their questions making them more focused when they do come to ask questions about the document.

Extra careful pays off in the long run

Providing a simple explanation will only get you so far. Using steps to get the reader through the procedure is often a great way to get right to the point. Keeping the overhead of explaining the process to a minimum, so the reader can dive right in and get started will keep them focused on the task.

It also helps to include screen shots where appropriate. If the documentation must discuss a setting, show the screen the setting exists on to provide clarity and help ensure that the reader is following the correct path. Providing these extra screen shots and taking the extra effort when building the documents will save many questions down the road.

Take notes during any discussion

Taking effective notes can be a bit of a challenge. The notes part is easy, write down as much as possible in any meeting with users covering requirements or procedure or any meeting with users. Making effective use of the notes can be quite different. Many times when an employee asks for a feature or for help with an existing process, they will leave out some key information. Often times IT staff will think of this tidbit of information but expect the user who wanted the assistance will come ask about it.

More simply, if they didnt include it, it must not be necessary at this revision.

Providing good documentation should include listening actively to the users during any discussion. When they ask if a custom screen can be created in the application they use every day, do not skip the question. Instead, ask the entire group to help you understand the need for the screen and how it would be best used. This oftentimes will handle justification of development and get all questions out in the open. It will also involve the users in the process, which is vital for the documentation or customization to succeed.

And one more thing…

Look at your co-workers objectively when they ask you questions. Note: Do not objectify them, however or you could land in hot water.

Understand that their goal is to accomplish their tasks as quickly as they can. When the ask for clarification or help with an issue, your goal should not be to complete their task, just to get them what they need (or feel they need) to do their job as best they can. Excellent documentation, for any tasks that come up, can save everyone in the organization time and sometimes even help before the question is asked.

This isnt likely the only time I will look at documentation for users. The need for better than average documentation grows everyday and helping yourself or your staff to create the best possible documentation for your organization will be a huge positive for the IT department and the IT Manager.