WebJunction

Documenting your computer systems requires an investment of your time, but the payoff will be your staff’s quick acceptance of new systems and procedures since they’ll be able to master them quickly. By addressing the following principles, you can create a basic template for documenting any and all systems in your library. 

AUDIENCE

Consider the people who will be using the documentation.

Learning styles:  Do they learn best by watching a demonstration, touching the keyboard, or reading instructions?  Use slide presentations, mentoring and demonstrations to enhance your documentation.

Learning situation:  Will they be using this document as part of a hands-on training session or are they going to be sitting at their desk going through it alone?

Expertise:  Are they technically advanced or novices?

Motivation: Are they enthusiastic about learning this information or doing it reluctantly because someone told them they have to?

Admittedly, you will probably be creating documentation for a mix of people and situations, but design your documentation for those with the least expertise and motivation. If they lose their way in the documentation, they’ll lose their positive approach to learning the system and that spells trouble for successful training.

CLARITY

Make sure everyone will be able to understand your document.

Use a readable type: Don’t get fancy. Use a basic font like Helvetica, Times or other proven communicator. People are used to it and their eyes are trained to read it.

Eliminate jargon:    Not everyone is clear on all technical terms. If you need to use technical terms, define them either in the document when you first introduce the term or in a short list or glossary as close to their first use as possible, not at the end of the document.

Keep it simple:  Don’t introduce long explanations in the middle of your instructions. If you need to explain the reason for a particular system or procedure, do it before you get to the how-to instructions.

Use short sentences:  Keep the sentences short—preferably with one step per sentence. Or better yet, use a phrase, i.e. “turn counterclockwise” or  “press enter.”

Limit vocabulary:  Use words everyone will understand. This is no time to prove how smart you are.

VISUAL CUES

Use graphics to cue your audience, and be consistent in the way you use them.

Bullets and numbers:  Bullets say “pay attention.” Numbers say “do it in this order.” Use them for lists of steps or to call attention to a list of priorities.

Font styles:    Bold, italic and underline signify that you are making an important point. Use them for specific applications and use them the same way throughout your documentation.

Paragraphs:    Paragraphs signal separation of ideas. Use them to help your learners take a deep breath before moving to the next step.

Graphics:    A visual of the computer screen, network connections and other graphics can help your audience understand what to expect. You can call attention to definitions or warnings by putting a box around them. You can call attention to a helpful tip by placing it next to a graphic. You can even help fearful or unmotivated learners by placing humorous graphics with encouraging words throughout the document.

COMPREHENSIVENESS

Make sure you double and triple check for places a new learner will stumble. Your documentation will fail if you haven’t included all the necessary elements.

Don’t skip steps:  Sit down at your computer and go through the documentation yourself. Experts tend to assume steps that learners may not realize are necessary.

Include definitions: Whenever you use technical terms that you are not absolutely sure everyone will understand, define them. Make the definition clear and concise.

Combine learning styles:    Whenever possible provide the same documentation you used in a hands-on training for documentation at staff stations. Consistency will go a long way toward speeding the learning time. If you use a slide presentation in a demonstration, use the same bulleted lists or graphics used in a printed document. (One word of caution—screen printouts of a slide presentation are usually not as effective as a formatted document next to the computer station. Use both.)

TESTING

Beta testing is a proven theory in hardware and software development and it will work for you. Before you send out your documentation to the full staff, pick out one or two willing staff members to test the document. Put them in a situation similar to where the documentation will be used and tell them to find the errors. They will. Fix the errors.

TRIAL BY FIRE

Send your documentation out into the world. You will learn soon enough whether it’s working or not. When you start hearing, “I just don’t get this!” or “I don’t understand what you’re saying here,” take another look at the document. Sometimes it’s a people problem, but often it’s a problem with your documentation or presentation. Books and manuals are revised for a reason and your documentation will probably have to be too.

FEEDBACK 

Do some investigation and solicit feedback from the staff. Do a short survey with multiple-choice answers (but keep it short). Include a place for people to free-write their answers, suggestions or complaints. Don’t take it personally or blame the messengers if they’re critical. If you see confusion or complaints that point out the same problem more than once, it means the documentation has a flaw that will have to be fixed. If you hear compliments and kudos, it means you have found a formula that works and can move on to bigger and better documentation challenges. Give yourself a pat on the back.

REVISE

The principals of documentation remain the same. But, as situations, software, hardware or people change, you should revisit documentation to see if it needs to be revised. When younger staff members appear, you may find that a slide presentation on CD may become a much more effective way to document a system than a written document. Some libraries might have the staff and expertise to create video documentation. Use whatever technology is effective and feasible. Out of date documentation can cause confusion and, after all, you’ve already done most of the work so a revision will be simple. Happy documenting!