Update and Document Operational Procedures

HALABA TVET COLLEGE

INFORMATION TECHNOLOGY SUPPORT SERVICE

Level II

LEARNING GUIDE # 8

Unit of Competence : Update and Document

Operational Procedures
Module Title : Updating and Documenting
Operational Procedures
LG Code : ICT ITS2 M02 L03 08
TTLM Code : ICT ITS2 TTLM02 0516

LO 3: Update documentation

Introduction Learning Guide #8

This learning guide is developed to provide you the necessary information regarding the
following content coverage and topics

 Writing Technical and User Documentation

This guide will also assist you to attain the learning outcome stated in the cover page.
Specifically, upon completion of this Learning Guide, you will be able to –

 Review current version of technicaland user documentation based on the latest

operational procedures.
 Compare accuracy of technicaland user documentation with current systemfunctionality.
 Identify and document inaccuracies for future reference.

Learning Activities
Prepared by ADISU MEKONEN 1|P a g e
 Update and Document Operational Procedures

1. Read the specific objectives of this Learning Guide.

2. Read the information written in the “Information Sheets 1” in pages 3-6.
3. Accomplish the “Self-check” in pages 7.
4. If you earned a satisfactory evaluation proceed to “Information Sheet 2”. However, if your
rating is unsatisfactory, see your teacher for further instructions or go back to Learning
Activity # 1.
5. Read the information written in the “Information Sheet 2” in pages 8-11.
6. Accomplish the “Self-check” in page 12.
7. If you earned a satisfactory evaluation proceed to “Lap Test”. However, if your rating is
unsatisfactory, see your teacher for further instructions or go back to Learning Activity # 2.
8. Do the “LAP test” on page 13 (if you are ready) and show your output to your teacher. Your
teacher will evaluate your output either satisfactory or unsatisfactory. If unsatisfactory, your
teacher shall advice you on additional work. But if satisfactory you can proceed to Learning
Guide 7.

 Your teacher will evaluate your output either satisfactory or unsatisfactory. If

unsatisfactory, your teacher shall advice you on additional work. But if satisfactory you
can proceed to the next topic.

Prepared by ADISU MEKONEN 2|P a g e

 Update and Document Operational Procedures

Information Sheet 1 Writing Technical and User Documentation

A fundamental problem
• Whose fault is that? The users’ or the writers’?

Why don’t people read manuals?

• “No time.”
• “Can’t find what you are looking for.”
• “Can’t understand a thing.”
• “The instructions don’t work.”
• “What I want to do isn’t in the manual.”

Parts of a technical document as a package

Writing good documentation is a team effort!

Types of documentation
• Tutorial
• General, thematic
• Reference
• How to/FAQ

A few questions to ask before writing …

• Who will use the document?
• How will they use it?
• Does the documentation contain the information to help achieve their goals?

Audience characteristics
• IT skill level
• contextual knowledge (e.g. about similar programs)
• type
Prepared by ADISU MEKONEN 3|P a g e
 Update and Document Operational Procedures

– programmer/developer
– end user
• frequent
• occasional
• rare
Many times: multiple audiences.

Some quality aspects of good documentation

• concise
• complete
• up-to-date
• free of jargon
• well organized
• accurate
• consistent

Parts of a good user manual

• Table of contents (two levels if necessary)
• Conventions
• What’s new
• Content
• Appendix
• Index

Writing approach
• define audience, goals and content
• assume (almost) nothing about your reader
• put yourself in the reader’s position
• use conventions and a style guide
• be consistent
• avoid jargon

Information design approach

• information:
– create a hierarchy of importance
– create a hierarchy of content
• clear, consistent layout
• user actions paired with outcomes
• create multiple entry points to information
• direct labelling

Prepared by ADISU MEKONEN 4|P a g e

 Update and Document Operational Procedures

A fundamental tenet
“Good information design is invisible …”
Titus Schleyer, today

… but mistakes in information design might not be visible to you.

Usability testing for documentation

• Give users a formal task; use think-out-loud protocol.
• Hand your documentation to a user with a real problem.
• Have developers review your documentation.

Prepared by ADISU MEKONEN 5|P a g e

 Update and Document Operational Procedures

How to Write User Documentation?

Types of User Documentation

1. User Guide
2. Reference Manual
3. Online Help

User Guide
• A user guide is task-based documentation. A user guide is document that explains how to
use software to do procedures. A user guide answers the question, "How do I…?"
• Example: How to uninstall software from your computer

Reference Manual
• A reference manual is a document that explains the parts of a product. A reference manual
answers the question, "What is x?"
• Example: What is RAM; What is SATA; What is Bus Width

Online Help
• Online documentation is also known as online help, on-screen help, and Help.
• Online documentation is designed to be viewed on a screen. Therefore, online
documentation has an aspect ratio that is suitable for viewing on a screen.

Online Documentation
Some formats for online documentation are as follows:
• Compiled HTML Help is a Windows help format.
• WebHelp and FlashHelp are proprietary cross-platform help systems from Adobe.
• HTML help.
• WinHelp is for legacy systems only. WinHelp is not supported in Windows Vista.

How to write

Where do we start? This article gives you guidance…

1. The Business Case

Typical reasons for producing user documentation are to:
• Help the users of your software
• Decrease your support costs
• Use as a marketing tool
• Improve your company's image.

*Before you start to produce the documentation, identify the reasons for producing the
documentation.
Prepared by ADISU MEKONEN 6|P a g e
 Update and Document Operational Procedures

2. Audience analysis
One way to categorize the audience is by job role.
For example:
• Data entry clerk
• Supervisor
• System administrator
• Service desk operator.

3. Task analysis
A task is a set of operations that is used to achieve a goal.
To find the tasks and the procedures that people do:
• Observe users and talk to them about their jobs.
• Get information from existing documentation and from functional specifications.
• Match the tasks to known practice. For example, if one task is to create a record, other
tasks are necessary to select, change, and delete (or archive) records.

4. Structure and content

When you create a document, do one or more of the following:
• Divide the document into sections based on roles, for example, 'data entry' and
'administration'.
• Match the procedures to tasks. Group similar tasks into the same chapter.
• Organize chapters so that frequent tasks come before infrequent tasks.
• If you need both task-based instructions and reference material, divide the document into
two sections. The first section is a user guide. The second section is a reference manual.
The user guide contains short procedural information. It does not explain each field in
each dialog box. Instead, it contains cross-references to the reference section.
• You are an expert who knows the terms, the assumptions, and the shortcuts in the subject
area. Do not make logical jumps that non-experts do not understand. Possibly, you must
'state the obvious', because the audience does not know the subject. However, do not give
information that is not necessary. If one sentence is sufficient, do not include a page of
screen shots.

Prepared by ADISU MEKONEN 7|P a g e

 Update and Document Operational Procedures

Self – Check Written Test

Name: ______________________________________ Date:

________________________________________

I. MATCHING TYPE. Match the terms in column B with the description given in each item in
column A. Write the letter of your answer in the space provided before each item.

COLUMN A COLUMN B
______1. Part of the technical document is the A. Content
designer’s, developer’s and programmer’s B. Everyone
responsibility. C. What’s New
______2. Responsible for usability of the technical D. Usability
document. E. User guide
F. Online help
______3. Part of a user manual that consists things that G. Task
are the new features about the product. H. Used as a
______4. It is the measure of how useful the document marketing tool
is to the audience. I. Free of jargon
J. Reference Manual
______5. A kind of user documentation that answers
K. Concise
the question “How do I…?”.
L. Updated
______6. User documentation designed to be viewed
on a screen.
______7. It is a set of operations that is used to achieve
a goal.
______8. It means that the documentation can increase
the awareness of the readers about the product.
______9. It is a quality aspect of a good documentation
that means that it should consists of simple and
understandable terms / words.
______10. A document that explains the parts of a
product.

I. TRUE OR FALSE. Write True if the statement is correct, otherwise, write False.
___________1. Developers can review the usability of the documentation.
___________2. Documentation increases the support cost of the company.
___________3. Getting information from existing documentation is one way to find the tasks
and the procedures that people do.
___________4. In writing a user manual, you should assume that the user knows everything.

Prepared by ADISU MEKONEN 8|P a g e

 Update and Document Operational Procedures

___________5. Multiple entry points should be created to access information in the user
manual.

II. ENUMERATION. List down what are asked in each item.

1. Type of user documentation
_________________________ _________________________
_________________________

2. Reasons for producing documentation

_________________________ _________________________
_________________________ _________________________

3. Ways to test the usability of the documentation

______________________________________________________________________
___________
______________________________________________________________________
___________
______________________________________________________________________
___________
4. Writing approaches
_________________________ _________________________
_________________________
_________________________ _________________________
_________________________

Note: Satisfactory rating - 16 points Unsatisfactory - below 16 points

You can ask you teacher for the copy of the correct answer

Prepared by ADISU MEKONEN 9|P a g e