Training, Teaching and Learning Materials (TTLM)

The Ethiopian TVET-System

Information Technology Support
Servicing
Level II

Learning guide
UNIT OF COMPETENCE: UPDATE AND
DOCUMENT OPERATIONAL PROCEDURES
MODULE TITLE: UPDATE AND DOCUMENT
OPERATIONAL PROCEDURES
LG CODE: EIS ITS2 MO2 LO1-LO2
TTLM Code: EIS ITS2 M02 1019
LEARNING OUTCOME:-
LO 1: Assess technical and user documentation
LO 2: Updating Operational Procedures
LO 3: Update Documentation

September, 2022

LO 1: Assess technical and user documentation

Introduction Learning Guide #6

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 technical and user documentation based on the latest
operational procedures.
 Compare accuracy of technical and user documentation with current system
functionality.
 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 you’re 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
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, 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

 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

Information Sheet 2 Accuracy Review of Technical and User

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.

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, hum or less 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.

  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 Mark-up Review

In order for these scripts to work, documents must use valid mark-up and include specific
metadata.

Mark-up 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 Mark-up

 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:

 Article info or book info

 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
author group. If the document was prepared by an organization with no individual author,
please use author corp instead.
 Editor. Every new document must go through the review process and have a technical,
language and metadata/mark-up review editor listed
 Pub date. 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.

Self – Check Written Test

Name: ______________________________________ Date:

________________________________________

Time started: _______________________________ Time finished:

_______________________________

I. MATCHING TYPE. Match the terms in Column B with the appropriate description in
Column A.

COLUMN A COLUMN B

1. It is a documentation that is designed for the end a. Abstract

 user of a computer hardware or software b. Accuracy
2. It is the process of providing evidence. c. Conciseness
3. A documentation that provides a more general d. Documentation
information about the product like transportation, e. Grammar
storage, installation, usage and cleaning, service f. Markup
repair and ends up with dismantling and disposal. g. Metadata
4. A document that details the procedures for a specific h. Peer review
workplace. i. Readability
5. Review by people who have coordinated knowledge j. Technical
and skills. documentation
6. Correctness of the information k. Title
7. Whether or not the way the document is written truly l. User direction
interferes with the readers understanding of the m. User documentation
information.
8. Address issues such as standards of subject/verb
agreement, pronoun/antecedent agreement, etc
9. A short description of the document.
10. Information about the document.

II. ENUMERATION. List what is asked for in every item.

1. List down at least five (5) required metadata in the document.

2. Identify at least ten (10) items in the document to be evaluated and describe each briefly
(in one sentence only).

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

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

LO 2: Updating Operational Procedures

Introduction Learning Guide #7

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 technical and user documentation based on the latest
operational procedures.
 Compare accuracy of technical and user documentation with current system
functionality.
 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 you’re
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 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 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.

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.

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.

Name: ______________________________ Date: ____________________________

I. TRUE OR FALSE. Write true if the statement is correct and write False if it is
incorrect. Write your answer in the space provided before each item.(10 points)
________1. OPs are intended to be specific to the organization or facility whose
activities are described.
________2. The information presented in SOPs should be ambiguous and overly
complicated.
________3. “YOU” can be freely used in SOP to address the instruction to the reader.
________4. Current copies of SOPs should be readily accessible for reference in the
work areas.
________5. SOP should be updated and re-approved whenever there are changes in any
of the procedures of the organization.
________6. During revision, the whole SOP should be revised.
________7. An OP should be written by an individual who has a little knowledge about
the activities and the organization’s internal structure.
________8. It is especially helpful if draft SOPs are actually tested by the original writer
before it can be finalized.
________9. SOP should be written in concise, step – by – step, easy – to – readformat.
________10. Quality Management Plan is responsible for maintaining a file listing of all
current quality-related SOPs used within the organization.

II. ENUMERATION. Give what is/are asked in each item.

1. Other terms for OP

_______________________ _______________________
_______________________ _______________________

2. Instances where OP fails

_______________________ _______________________

3. Information indicated in the Title Page

_______________________ _______________________
_______________________ _______________________

III. IDENTIFICATION. Identify the term being described in each item. Write your answer
in the space provided
Before each item.
______________________1. An operating procedure is a set of written instructions that
document a routine on what activity of the organization?
______________________2. What happens to the best written SOP when not followed?
 ______________________3. It indicates the frequency of review and the individual
responsible for ensuring that SOPs are current.
______________________4. Used as quick reference especially for long SOPs.
______________________5. Who is responsible for maintaining a file listing all current
quality-related SOPs used within the organization?
Note: Satisfactory rating - 20 points Unsatisfactory - below 20 points
You can ask you teacher for the copy of the correct answer

Other terms used to mean operating procedures (protocols, instructions, worksheets, laboratory
operating procedures)
1. (repetitive)
2. fail)
3. When do SOPs of limited value? (not written correctly, not followed)
4. Are OPs specific to an organization? true
5. Current copies of SOPs should be readily accessible for reference in the work areas (hard
copy or electronic format). (true)
6. SOP should be written in what format? (concise, step – by – step, easy – to – read)
7. What kind of voice should be used in writing SOP? (active)
8. The information in the SOP should be conveyed ___________ and ______________ to
remove doubt as to what is required. (clearly, explicitly)
9. It is used by the organization to have consistent format on font size, margins and other
format styles. (style guide)
10. What term should not be used in SOP because it is already implied?
11. An OP should be written by an individual who has a little knowledge about the activities
and the organization’s internal structure.
12. What approach can be followed especially for multi-tasked processes because the
experiences of a number of individuals are critical? (team)
13. It is especially helpful if draft SOPs are actually tested by the original writer before it can
be finalized.(False)
14. Who review and approve SOPs (immediate supervisor, section or branch chielf, QA
officer)
15. Indicates that an SOP has been both reviewed and approved by management. (signature
of approval)
16. SOP should be updated and re-approved whenever there are changes in any of the
procedures of the organization.
17. During revision, it is possible to modify only specific section and not the whole SOP.
18. It indicates the frequency of review and the individual responsible for ensuring that SOPs
are current. (Quality Management Plan)
19. What are the considerations in the review and revision process of SOP? (SOPs need to
remain current-recent to be useful, SOPs should be also systematically reviewed on a
periodic basis, The review process should not be overly cumbersome-burdensome)
20. Who is responsible for maintaining a file listing all current quality-related SOPs used
within the organization? QA Manager
21. What are the information written in the Title page (title, 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)
22. It is information in the title page that clearly identifies the activity or procedure.
23. Used as quick reference especially for long SOPs.

Name: _________________________________ Date: ______________________________

I. IDENTIFICATION. Identify the term described in each item. (10 points)

_______________________1. A set of written instructions that document a routine on
repetitive activity followed by an organization.
_______________________2. The development and use of SOPs can minimize what factor
in the implementation of a process or procedure within the
organization.
_______________________3. What tense of the verb should be used when writing SOP?
_______________________4. It is used to illustrate the processing described.
_______________________5. It indicates that an SOP has been reviewed and approved by
the management.
_______________________6. The typical length of time (number of years) to review SOP.
_______________________7. Generally, the one responsible for maintaining a file listing
all current quality-related SOPs used within the
organization.
_______________________8. Contains the list of SOP contents and the corresponding
page number in the manual.
_______________________9. Contains the description of the work or process.
_______________________10. It means that the SOP is updated.

II. ENUMERATION: Enumerate the items asked in each item. (10 points)
1. The three characteristics of SOPs, in terms of how it should be written.

_______________________________
_______________________________
_______________________________
2. Give four (4) important information that should be indicated in the master list of SOP.

_______________________________
_______________________________
_______________________________
_______________________________
3. Three(3) main parts of an SOP
 _______________________________
_______________________________
_______________________________

III. Identify the following items as to what SOP process it belongs. Write A if it is an
activity in the SOP Preparation, B if it is in SOP Review and Approval or C if in the
SOP Document Tracking an Archival. (6 points)
_____1. Identify the procedures / processes need to be documented.
_____2. The Quality Management Plan should indicate the individuals responsible for
assuring that only the current version is used.
_____3. SOPs need to remain current – recent to be useful.
_____4. The organization should maintain a master list of all SOPs.
_____5. Team members / an individual should be identified who will be responsible to
write the SOP.
_____6. The review process should not be overly cumbersome – burdensome.

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

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

Self – Check Answer Key

I. IDENTIFICATION
1. SOP
2. Variation
3. Present tense
4. Flowchart
5. Signature of approval
6. 1-2 years
7. QA manager
8. Table of Contents
9. Text
10. Current – recent
II. 1.a. Concise b. step – by – step c. easy – to – read format
2. a. short title / ID # b. Rev # c. Date d. Page number
3. a. title b. table of contents c. text

III. 1. A
2. C
3. B
4. C
5. A
6. B
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 –

 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 technical and user documentation based on the latest
operational procedures.
 Compare accuracy of technical and user documentation with current system
functionality.
 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 you’re 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 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)
• 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 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.

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.