ADMAS UNIVERSITY

Information Technology Support Service Level II

Learning guide
Unit of Competence: Update and document operational procedure
Module Title : Update and document operational procedure
TTLM Code : ICT ITS2 02 0710

Lo 1: Assess technical and user documentation

Lo 2: Update procedures
Lo 3: Update documentation
 UPDATE AND DOCUMENT OPERATIONAL PROCEDURE

Information sheet LO-1 Assess technical and user documentation

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

 User and Technical Documentation Review

 Accuracy Review of 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

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.

Information Sheet 1 User and Technical Documentation Review

ADMAS UNIVERSITY – BISHOFTU CAMPUS Page 2

 UPDATE AND DOCUMENT OPERATIONAL PROCEDURE
Documentation may refer to the process of providing evidence ("to document something") or to the communicable
material used to provide such documentation (i.e. a document).

Documentation in ICT field: The following are different types of documentations usually seen in the ICT field.

1. Architectural and Design documentation.

2. Technical Documentation.
3. User Documentation.
4. System Documentation.
USER AND TECHNICAL DOCUMENTATION

1. User documentation - Designed for the end user of the computer hardware or software. It may not be a computer
specialist
Examples of user documentation
 Instructional Materials which usually come with the hardware or software such as installation
instructions or a troubleshooting guide.
 Training Materials designed to teach the user the skills required to use the hardware or software.
Examples include tutorials and user manuals.
 Reference Materials designed so users can look up a particular task. An example is a quick reference
guide.
 Policies and Procedures of an Organization. This documentation helps all staff and management work
to the same guidelines and rules.
2. Technical documentation- "Technical documentation" is the generic term for documentation with regard to a
product. People mainly associate the term with the documents and information that are passed on to the public by the
manufacturer.
It is also a documentation that is produced for a person who has enough expertise in a particular computer
system to support or maintain that system.
Examples of technical documentation
 User instructions
 Operating instructions
 Servicing instructions
 Installation manuals
 Software manuals
The term 'technical documentation' refers to different documents with product-related data and information that are used
and stored for different purposes. “Different purposes” mean: Product definition and specification, design, manufacturing,
quality assurance, product liability, product presentation; description of features, functions and interfaces; intended, safe
and correct use; service and repair of a technical product as well as its safe disposal.
Instructions versus directions versus manual versus handbook versus …

Often, there is still confusion about whether something should be called operating instructions, user manual,  user guide,
user directions, operating manual etc. pp. The standards for technical editors and the law makers are also not consistent in
their terminology. Let's try to sort it out from a linguistic point of view:

 "Directions" is derived from "to direct": Here it is the superior who directs the subordinate, i.e. the
boss directs the staff member (or parents their child). Hence, user directions can only be given internally (within the
company). Accordingly, the user direction is the document that details the procedures for a specific workplace. It
takes into account the specific demands and requirements within the company. This makes it clear that user directions
cannot be supplied by the manufacturer of the product: the manufacturer has no knowledge of the company internals
of the user.
 "Instructions" is derived from "to instruct". Somebody capable of something already instructs
someone else who wants to learn just this. Here two entities meet eye-to-eye, e.g. manufacturer and user. Therefore,

ADMAS UNIVERSITY – BISHOFTU CAMPUS Page 3

 UPDATE AND DOCUMENT OPERATIONAL PROCEDURE
the instructions are the document that communicates, how to employ and use the product. When "instructing"
however, you do not really communicate any theory, i.e. the description of the product is — strictly speaking — not
part of the instructions. The term "instructions" is independent of the publishing medium, it does not tell you
whether it comes on paper or online
 "User instructions" or "user manual": The first word of each group already says it — it is about
using the product. Because "manual" is usually associated with a "book", "user manual" is the book, in which the
usage is described. The publication medium is specified. On the other hand, the term "user instructions" is media
independent.
 Operating instructions / operating manual: Here again it is all about the first word in the phrase —
it is generally about the operation. This is more general than just using something; it starts with transport and storing,
is then followed by installation and commissioning up to using the product, continues with cleaning, service and
repair and ends up with dismantling and disposal. A document describing operating should therefore be
correspondingly comprehensive (not forgetting the safety information).
REVIEW CURRENT VERSION OF TECHNICAL AND USER DOCUMENTATION
Why Documentation Review?
 Overall improvement
 Accurate and up-to-date documents
 Increases credibility
The Need
 Technically correct document
 Concise Information
 Avoid Chaos/disorder
 Timely Delivery
 Satisfaction
Review Objectives
 Evaluate the documented information
o Accuracy = Correctness
o Completeness = wholeness
o Conciseness = shortness
 Reduce the defect percentage
 Improve the quality of documents
 Focus on correcting the defects
Types of documentation reviews
1. Peer Review
o Review by people who have coordinated knowledge and skills.
 Provide a list of exactly what you need them to review
o Assess peer review practice
o Prepare procedure documents
o Formulate a program agenda
2. Presentation Review
3. Review amongst the technical writers
4. Subject matter expert review
5. Review for technical information
6. Overall Review
7. Review by the testing team for detecting defects.

The Review Process

1. Plan the review process
2. Develop a clear, focused charge for each reviewer to identify important issues and invite
suggestions for improvement.
3. Prepare and maintain a review record.
4. Make recommended changes to document and respond to the reviewer’s comments.
Review Focus

ADMAS UNIVERSITY – BISHOFTU CAMPUS Page 4

 UPDATE AND DOCUMENT OPERATIONAL PROCEDURE
 Before circulation
o Review the document for readability and clarity.
o Review for correct English usage
o Review and evaluate the technical content
o Make a reviewers checklist
 Focus on the technical review and not on editorial review
 Verify the technical accuracy of all procedural steps.
 Verify the accuracy of all screen captures in the document.
 After review
o Review the sent checklist
o Take a positive approach
o Maintain a tracking list
o Decide and let the reviewer know which comments would be incorporated
o Call a meeting if required.
o Publish the final copy.
Challenges
 Involving Team (Let us do it)
 Getting Proper reviews
 Handling Last Minute Changes

Accuracy Review of Technical and User

Information Sheet 2
Documentation
Comparing accuracy of technical and user documentation’s with the current document (functionality will be
treated later)
Make sure the facts as stated in the document are correct, helpful, and on topic.
To do a technical accuracy review, you really need to know your subject matter, probably as well or better than
the original author. Use whatever other documentation is available for your subject, including man pages, program
documentation, other printed books, etc. You might also use mailing lists on the topic, asking for third parties to verify
certain facts of which you are in doubt.
When doing this type of review, consider if the information is only valid for certain types of hardware or
software. If this is the case, make sure to note the limitations of the document within the document, either within the
abstract or as a note at the beginning of the document. For example, if the solutions in the document only are relevant for
one type or brand of hardware, make sure that that limitation is defined. This will keep readers from trying to apply a
certain type of technology to an application or situation where it will not work.
The same should apply for the prerequisite knowledge of the reader. If prior knowledge of a subject is assumed or
required, the author should say so somewhere at the beginning of the document, and it's helpful to ask that authors provide
a Resource section for further reading, to bring readers that much closer to the required information.
Language Review

Because writers come from all types of backgrounds, there may be problems within the documentation that need
to be fixed. Writers may be very knowledgeable in their subject areas but not great writers, or they may be excellent
writers but not completely fluent in the language of the document. The language review addresses these types of problems
by focusing on language issues that make the document easier for the user to read and understand. Some of the problems
that may occur within the document are poor sentence structure, grammar, organization, clarity, and spelling.

If you are doing a language review, you should be fluent in the language and the structure of the language. You
want to consider both the logic and grammar of the document. Your primary goal in a language review is to identify and
correct areas that could lead to confusion for the reader/user of the document. To this end, you can most certainly use
language and grammar references such as dictionaries and handbooks when in doubt.

ADMAS UNIVERSITY – BISHOFTU CAMPUS Page 5

 UPDATE AND DOCUMENT OPERATIONAL PROCEDURE
Although this review does address the structure and delivery of the language, you should not attempt to purge the
document of individuality and personality in an attempt to make it "sound better" or more technical. Stilted or overformal,
humorless language and structures are not the goals here. Again, your goal should be to make the document clear,
unambiguous, and correct in spelling and grammar.
Items to evaluate:
 Spelling. Spelling should conform to a standardized English spelling of terms. For words that are new to the
language and not yet standardized (for example technical Linux terminology that is generally accepted in the
community), follow the most common spelling for the term.
 Grammar. For the purposes of this review, grammar should address issues such as standards of subject/verb
agreement, pronoun/antecedent agreement, etc
For example, to say, "You will need to set several parameters in the config file to make it compile correctly. The
ones you choose to set make a big difference."
 Use of capital letters. The document's title and section headings may follow one of two conventions, but must be
consistent throughout. Titles may either capitalize only the first word, or may capitalize each word. In the second
case the only words not capitalized in a title are prepositions, articles, and proper nouns which would not be
capitalized.
 Clarity. Judgments on clarity are sometimes difficult to make. One successful strategy in evaluating clarity is
asking the question "If I did not already know this information, would the explanation be clear from this
document." If it is confusing to you and you already generally understand what the author is trying to say, then
there is a good chance that the explanation is really confusing for someone reading the document for the first
time. If you run across this situation, and you don't really know how to correct the technical explanation, or you
are afraid your changes might affect the meaning of the document, ask for help from a technical expert. If no
technical expert is available or no one responds to your requests, note the needed changes in the review and mark
that these concerns need to be addressed in the technical review.
 Organization. In some cases the document would really benefit from a different structure. You should address
these issues when they interfere with the understanding of the information within the document. If a document
gives background information after a procedure has been performed, this may well be too late for the reader to
fully consider the information he or she needs before performing the task. Look for document organization that
might confuse or mislead the reader. These will be the types of issues you want to address. Once these are
identified, it may be worthwhile to let the author know your rationale and discuss major changes with him or her.
 Sentence Structure. To some extent, sentence structure issues are discussed in the grammar section; however,
there are some additional issues that are not grammatically incorrect but do interfere with the readers
comprehension of the material. One of the most noticeable of these is stacked prepositional phrases.
Stacked prepositional phrases become a problem when the document's readability suffers because it becomes less
and less clear what the subject and action of the sentence are. In some cases more precise descriptors are needed
or sentences need to be changed from one long sentence that is hard to comprehend, to two or three more easily
read sentences.
 Readability. This area is somewhat subjective. What passes for fairly readable material to one person might be
confusing to someone else. Because this is a value judgement you should be cautious when marking up an
author's work for readability. Realize when basing a judgment on readability that you might be dealing with
preferences of style. In evaluating readability you must consider whether or not the way the document is written
truly interferes with the readers understanding of the information. If the answer you come up with is "No, but it
doesn't sound like I think it should." then you should probably not re-write the text to make it sound better to you.
 Title. The title should be in proper title case. The general principle for this is that all words are capitalized in a
title except prepositions and articles (an article will be capitalized if it is the first word in the title).
 Date Formats. Dates should be in standard ISO format, which is YYYY-MM-DD.

ADMAS UNIVERSITY – BISHOFTU CAMPUS Page 6

 UPDATE AND DOCUMENT OPERATIONAL PROCEDURE
 Definitions of Acronyms or Slang. Terminology and language within the realm of computer technology changes
rapidly. In reviewing documents you may find that many of the terms that are being discussed are not valid words
in any dictionary or technical reference that you are familiar with. Terms that are less familiar should be defined
immediately following the first instance of the term. Slang should be replaced with more common terminology if
the slang will causes the reader to be confused by the connotation or denotation of the term.
Remember that readers using the document may not come to English as a primary language and, therefore, you
should do your best to make sure that the document is as easy to understand as possible.
 Latin abbreviations. Avoid using abbreviations. e.g. (for example), et al. (and others), etc (and so on) and i.e.
(that is) should always use the English equivalent.
Metadata and Markup Review
In order for these scripts to work, documents must use valid markup and include specific metadata.
Markup is a modern system for interpretation of a text in a way that is syntactically distinguishable from that
text. Example XML, Pdf, docs …
Metadata is information about the document and includes author information, copyright, license and a revision
history of the document.
Required Markup
 DocBook XML version
 PDF
 CHM (Compiled HTML Help): The CHM file type is primarily associated with 'HTML Help' by Microsoft
Corporation.
Required Metadata
The following elements are all required:
 articleinfo or bookinfo
 Title. Every document must contain a short, descriptive title. It should be reasonably unique; check other
documents in the collection to make sure your document's title is distinctive from all other documents.
 Abstract. A short description of your document must be included in the abstract. This description is typically one
or two sentences in length.
 Author. Every document must have an author. If there are multiple authors, you may use authorgroup. If the
document was prepared by an organization with no individual author, please use authorcorp instead.
 Editor. Every new document must go through the review process and have a technical, language and
metadata/markup review editor listed
 pubdate. The date of publication for the document. The date should be in the ISO standard of YYYY-MM-DD.
 Copyright. Authors will always retain the copyright to any documents they submit to the LDP. Although it is not
required, a copyright notice may be included. A license, however, is always required.
 Revision history (revhistory). A summary of revisions should be included in the document. The initial release of
a document should be marked up as Version 1.0. Subsequent updates should increment the version number
appropriately. The preferred format is Major.Minor.Bugfix, where each section is an integer. Some authors use
Alan Cox style versions (for example 1.4pre-3) and some include additional information (for example 1.3beta).
This is acceptable but not encouraged. The most important thing is that we have a version number so we know
which version we are dealing with! Once a document goes through review it should advance in minor or bugfix
version number, depending on the amount of change introduced.
 License and Legal Notice. A license is required.
 email.
 Acknowledgements and Other Credits. Very few, if any, documents are written only by one person. It is good
form to thank those who helped you with either the writing, research, testing or reviewing of your document. If
someone added markup, or translated your document to another language they should also be given credit.

ADMAS UNIVERSITY – BISHOFTU CAMPUS Page 7

 UPDATE AND DOCUMENT OPERATIONAL PROCEDURE

Information Sheet LO2 Update procedures

Introduction Learning Guide #2

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

 User and Technical Documentation Review

 Accuracy Review of 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

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.

ADMAS UNIVERSITY – BISHOFTU CAMPUS Page 8

 UPDATE AND DOCUMENT OPERATIONAL PROCEDURE

Information Sheet 1 Updating Operational Procedures

Operational Procedures

An Operating Procedure (OP) is a set of written instructions that document a routine on repetitive activity
followed by an organization. The development and use of Ops are an integral part of a successful quality system as it
provides individuals with the information to perform a job properly, and facilitates consistency in the quality and integrity
of a product or end-result.
The term “OP” may not always be appropriate and terms such as protocols, instructions, worksheets, and
laboratory operating procedures may also be used. For this document “OP” will be used.
Purpose
OP details the regularly recurring work processes that are to be conducted or followed within an organization.
They document the way activities are to be performed to facilitate consistent conformance to technical and quality system
requirements and to support data quality.

They may describe, for example, fundamental programmatic actions and technical actions such as analytical
processes, and processes for maintaining, calibrating, and using equipment. OPs are intended to be specific to the
organization or facility whose activities are described and assist that organization to maintain their quality control and
quality assurance processes and ensure compliance with governmental regulations.

If not written correctly, SOPs are of limited value. In addition, the best written SOPs will fail if they are not
followed. Therefore, the use of SOPs needs to be reviewed and re-enforced by management, preferably the direct
supervisor. Current copies of the SOPs also need to be readily accessible for reference in the work areas of those
individuals actually performing the activity, either in hard copy or electronic format, otherwise SOPs serve little purpose.

Benefits

The development and use of SOPs minimizes variation and promotes quality through consistent implementation
of a process or procedure within the organization, even if there are temporary or permanent personal changes. SOPs can
indicate compliance with organizational and governmental requirements and can be used as a part of a personnel training
program, since they should provide detailed work instructions. It minimizes opportunities for miscommunication and can
address safety concerns.

Writing Styles

SOPs should be written in a concise, step-by-step, easy-to-read format. The information presented should be
unambiguous and not overly complicated. The active voice and present verb tense should be used. The term "you" should
not be used, but implied. The document should not be wordy, redundant, or overly lengthy. Keep it simple and short.
Information should be conveyed clearly and explicitly to remove any doubt as to what is required.

Also, use a flow chart to illustrate the process being described. In addition, follow the style guide used by your
organization, e.g., font size and margins.

SOP PROCESS

SOP Preparation

The organization should have a procedure in place for determining what procedures or processes need to be
documented. Those OPs should then be written by individuals knowledgeable with the activity and the organization's

ADMAS UNIVERSITY – BISHOFTU CAMPUS Page 9

 UPDATE AND DOCUMENT OPERATIONAL PROCEDURE
internal structure. These individuals are essentially subject-matter experts who actually perform the work or use the
process.

A team approach can be followed, especially for multi-tasked processes where the experiences of a number of
individuals are critical, which also promotes “buy-in”/interest from potential users of the SOP.

SOPs should be written with sufficient detail so that someone with limited experience with or knowledge of the
procedure, but with a basic understanding, can successfully reproduce the procedure when unsupervised. The experience
requirement for performing an activity should be noted in the section on personnel qualifications. For example, if a basic
chemistry or biological course experience or additional training is required that requirement should be indicated.

Write OP on how to uninstall software from your XP computer

SOP Review and Approval

SOPs should be reviewed (that is, validated) by one or more individuals with appropriate training and experience
with the process.It is especially helpful if draft SOPs are actually tested by individuals other than the original writer
before the SOPs are finalized.

The finalized SOPs should be approved as described in the organization’s Quality Management Plan or its own
SOP for preparation of SOPs. Generally the immediate supervisor, such as a section or branch chief, and the
organization’s quality assurance officer review and approve each SOP. Signature approval indicates that an SOP has been
both reviewed and approved by management.

Frequency of Revisions and Reviews

SOPs need to remain current-recent to be useful.Therefore, whenever procedures are changed, SOP should be
updated and re-approved. If desired, modify only the pertinent section of an SOP and indicate the change date/revision
number for that section in the Table of Contents and the document control notation

SOPs should be also systematically reviewed on a periodic basis,e.g. every 1-2 years, to ensure that the policies
and procedures remain current and appropriate, or to determine whether the SOPs are even needed. The review date
should be added to each SOP that has been reviewed. If an SOP describes a process that is no longer followed, it should
be withdrawn from the current file and archived.

The review process should not be overly cumbersome-burdensome to encourage timely review. The
frequency of review should be indicated by management in the organization’s Quality Management Plan. That plan
should also indicate the individual(s) responsible for ensuring that SOPs are current.

Document Control

Each organization should develop a numbering system to systematically identify and label their SOPs, and the
document control should be described in its Quality Management Plan.
Generally, each page of an SOP should have control documentation notation, similar to that illustrated below. A short title
and identification (ID) number can serve as a reference designation. The revision number and date are very useful in
identifying the SOP in use when reviewing historical data and is critical when the need for evidentiary records is involved
and when the activity is being reviewed. When the number of pages is indicated, the user can quickly check if the SOP is
complete.Generally this type of document control notation is located in the upper right-hand corner of each document
page following the title page.

ADMAS UNIVERSITY – BISHOFTU CAMPUS Page 10

 UPDATE AND DOCUMENT OPERATIONAL PROCEDURE
SOP Document Tracking and Archival

The organization should maintain a master list of all SOPs. This file or database should indicate the SOP number,
version number, date of issuance, title, author, status, organizational division, branch, section, and any historical
information regarding past versions. The QA Manager (or designee) is generally the individual responsible for
maintaining a file listing all current quality-related SOPs used within the organization. If an electronic database is used,
automatic “Review SOP” notices can be sent. Note that this list may be used also when audits are being considered or
when questions are raised as to practices being followed within the organization.
Short Title/ID #
Rev. #:
Date:
Page 1 of
As noted above, the Quality Management Plan should indicate the individual(s) responsible for assuring that only
the current version is used. That plan should also designated where, and how, outdated versions are to be maintained or
archived in a manner to prevent their continued use, as well as to be available for historical data review.
Electronic storage and retrieval mechanisms are usually easier to access than a hard-copy document format. For
the user, electronic access can be limited to a read-only format, thereby protecting against unauthorized changes made to
the document.
Submit procedure
Prepare standard procedure for installation of programs from CD/DVD on Windows 7 System.
SOP GENERAL FORMAT
SOPs should be organized to ensure ease and efficiency in use and to be specific to the organization which
develops it. There is no one “correct” format; and internal formatting will vary with each organization and with the type of
SOP being written. Where possible break the information into a series of logical steps to avoid a long list. The level of
detail provided in the SOP may differ based on, e.g., whether the process is critical, the frequency of that procedure being
followed, the number of people who will use the SOP, and where training is not routinely available. A generalized format
is discussed next.
 Title Page
The first page or cover page of each SOP should contain the following information: a title that clearly identifies
the activity or procedure, an SOP identification (ID) number, date of issue and/or revision, the name of the applicable
agency, division, and/or branch to which this SOP applies, and the signatures and signature dates of those individuals who
prepared and approved the SOP. Electronic signatures are acceptable for SOPs maintained on a computerized database.
 Table of Contents
A Table of Contents may be needed for quick reference, especially if the SOP is long, for locating information
and to denote changes or revisions made only to certain sections of an SOP.
 Text
Well-written SOPs should first briefly describe the purpose of the work or process, including any regulatory
information or standards that are appropriate to the SOP process, and the scope to indicate what is covered. Define any
specialized or unusual terms either in a separate definition section or in the appropriate discussion section. Denote what
sequential procedures should be followed, divided into significant sections; e.g., possible interferences, equipment needed,
personnel qualifications, and safety considerations (preferably listed in bold to capture the attention of the user). Finally,
describe next all appropriate QA and quality control (QC) activities for that procedure, and list any cited or significant
references.

As noted above, SOPs should be clearly worded so as to be readily understandable by a person knowledgeable
with the general concept of the procedure, and the procedures should be written in a format that clearly describes the steps
in order. Use of diagrams and flow charts help to break up long sections of text and to briefly summarize a series of steps
for the reader.

ADMAS UNIVERSITY – BISHOFTU CAMPUS Page 11

 UPDATE AND DOCUMENT OPERATIONAL PROCEDURE
Attach any appropriate information, e.g., an SOP may reference other SOPs. In such a case, the following should
be included:

1. Cite the other SOP and attach a copy, or reference where it may be easily located.

2. If the referenced SOP is not to be followed exactly, the required modification should be specified in the SOP at
the section where the other SOP is cited.

Information Sheet LO-3 Update Documentation

Introduction Learning Guide #3

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

 User and Technical Documentation Review

 Accuracy Review of 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

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.

ADMAS UNIVERSITY – BISHOFTU CAMPUS Page 12

 UPDATE AND DOCUMENT OPERATIONAL PROCEDURE
 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.

ADMAS UNIVERSITY – BISHOFTU CAMPUS Page 13

 UPDATE AND DOCUMENT OPERATIONAL PROCEDURE

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
– 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)

ADMAS UNIVERSITY – BISHOFTU CAMPUS Page 14

 UPDATE AND DOCUMENT OPERATIONAL PROCEDURE
• 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
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.
How to Write User Documentation
Types of User Documentation
1. User Guide
2. Reference Manual
3. Online Help
User Gu
• 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.
ide
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.

ADMAS UNIVERSITY – BISHOFTU CAMPUS Page 15

 UPDATE AND DOCUMENT OPERATIONAL PROCEDURE
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.
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.

ADMAS UNIVERSITY – BISHOFTU CAMPUS Page 16