AAMBC TVET COLLEGE

Hardware and Networking Service

Level III

Create Technical Documentation

JALETO S.
1
 Creating Technical Documentation

• LEARNING OUTCOMES:

• At the end the module the trainee will be

able to:
LO1 identify and analyze documentation needs
LO2 design documentation
LO3 develop documentation

LO4 evaluate and edit documentation

2
LO1 Identifying and analyzing documentation needs
• This learning guide was developed to provide you the
necessary information regarding the following content
coverage and topics –
– Introduction to documentation

– Consulting Clients

– Identifying documentation requirements

– Evaluating and interpreting documentation requirements

– Investigating Industry and documentation standards

– Defining and documenting the scope

3
Introduction to documentation
What is Technical Documentation?
• Documentation: is a package that contains Content,
Format, Layout, and Language, grammar, style to describes
the product to its users.
• In computer hardware and software product development,
documentation is the information that describes the product
to its users or it is simply the instructions for using a
computer device or program.
• Technical documentation refers to any type of
documentation that describes handling, functionality and
architecture (structural design) of a technical product or a
product under development or use.

4
 Types of user documentation
• When a new computer application is implemented or changes
are made to existing computer applications, documentation
that explains how the computer application works may need to
be provided directly to users and/or to the help desk.
• There are different types of documentation that can be
available for each computer application, for example:
– user manual/guide
– technical manual/guide
– Training manual/resources.

5
 User Guide cont’d
• A user guide shows the user:
• How to use the application, i.e the steps required to
complete various tasks
• Screens dumps with ‘dummy’ data to give the user a
complete picture of how to enter data and process
the data

6
 Tutorials cont’d
• Tutorials are lessons that take the reader by the hand
through a series of steps to complete a project of some kind.
• Note that this guide can incorporate a training resource
such as a tutorial.
• The technical manual generally contains the technical
information such as:
– system requirements to run the application
– how to install the application
– configuring the application
– database layout (if a database is used)
– screen layouts
– how to get technical support

7
 Consulting Clients
• At the end of any project to develop a
computer application, a copy of all
documentation should be provided to:
– the client
– the help desk
– The help desk can then provide support to
users when they contact them for support.

8
 Cont…
• The management consultancy industry is attracting
more and more attention. ... In particular,
• they have explored the interaction
between consultant and client, and called attention
to factors like the countervailing power
of client organizations and the uncertainty of the
management task.

9
 How to Market Yourself as a Consultant
• Define Your Niche. Consulting comes in
many shapes and forms. ...
• Show Personal Touch. As mentioned,
marketing your consulting business actually
means marketing yourself as a professional,
trustworthy, skilled and innovative person.
• Be Savvy. ...
• Master those Networking Skills. ...
• Online Presence.
10
 The role of an IT consultant
• is to be a technical specialist that focuses on integrating information
technology into businesses and showing clients how to use IT more
efficiently to help reach objectives and targets.
• This can be done by introducing new technical solutions and software
platforms to current IT infrastructures with the purpose to improve
processes and profitability.
• IT consultants typically work as the bridge between the technical team
and staff members by getting a clear understanding of the client
requirements of the business model and strategy.

11
There are different reasons a business may require
the assistance of an IT consultant:
• To seek advice and recommendations about
business and IT problems
• To diagnose and refine challenges & opportunities
• To make recommendations to improve team
effectiveness
• Implement new systems to increase productivity
and awareness
• To temporarily help during a project where the
hiring of permanent employees is not necessary
• External specialist advice

12
Responsibilities of a IT Consultant
• An IT consultant must be capable of reaching high
standards and having strong analytical skills to understand
potential issues and develop solutions.
• Time management and being able to multi-task is crucial as
well as having strong communication skills to understand
the needs and requirements of clients.

13
 Other duties may include
• Recognizing the requirements and scope of the business from the client
• Developing a plan of action including time scale and resources required
• Understanding the practices and nature of business
• Monitor the computer systems and networks in an organization
• Liaising with software engineers and IT support members
• Analyzing potential issues and presenting written or oral solutions
• Communicate in writing to understand the work that needs to be done
• Be willing to travel across the country or even overseas

14
 Reading assignment
• What is the difference between customer and
client
– Customers are generally people who come to you
mainly to buy products or services you supply.
– Clients buy your advice and solutions personalized
to their particular needs.

15
 Providing support to clients

• Providing Client support is not a piece of cake. It requires

patience along with good communication and people skills to
run an efficient support business.
• we need help from others from time to time. This fact holds the
greatest significance today when technology has pervaded to
each and every part of our existence.
• Today anywhere and everywhere we go, no matter what we do,
we are also accompanied by technology either in the form of a
phone or a PC or household appliances etc.
16
 Identifying documentation requirements

• A Documentation Requirements Specification

(SRS) (also known as a Software or Hardware
Requirements Specification) is a document or set of
documentation that describes the features and behavior
of a system or software application.
• It includes a variety of elements (see below) that
attempts to define the intended functionality required
by the customer to satisfy their different users.
17
 Requirements Documentation
• The Requirements Document lists all the
information that was elicited during the Discovery
phase and is the foundation for Design and
subsequent phases.
• The Requirements Document is used for:
– Management and control – to ensure that the project
stays in scope and deliverables are traceable to
requirements
– Design of the new system and processes
– Ensures stakeholder buy-in to the final product
– Basis for User Acceptance Testing and project sign-off

18
 Ensures stakeholder buy-in to the final product

• stakeholder is either an individual, group or

organization who is impacted by the outcome of
a documentation
– There are five major types of stakeholders:
• Project manager.
• Project team.

• Functional management.
• Sponsors.
• Customers.
19
20
 Requirements should be:
• Feasible; able implement and maintain within
constraints
• Necessary; required due to a business or customer need
• Be complete; each requirement should be a standalone
statement
• Consistent; no conflict between requirements
• Verifiable; requirement can be validated
• Traceable; uniquely identifiable so that it can be
tracked
• Design independent; specifies what is needed, not how
it should be provided
21
 General tips that can be used in writing the
Requirements Document:
• Use active voice to document each requirement; i.e. Track
Purchase Orders rather that Purchase Orders should be
tracked
• Spell out and define abbreviations the first time used, i.e.
Information Technology Services (ITS)
• Maintain consistent level of detail
• Categorize requirements into related groups
• Examine requirements for consistency, omissions and
ambiguity
• Prioritize requirements based on customer need
• Use quantitative measures (response time of 1 second or less)
instead of qualitative descriptions (quick response time) so
that achievement is measurable
22
 Cont…
• Due to cost and/or time constraints, it is improbable
to find or customize a system that meets all business
requirements.
• Therefore it is important to prioritize requirements:
– Critical (must have): core functionality that system must
have in order to be successful
– Important (should have): requirements that would
enhance performance and should be included, if possible
– Desirable (nice to have): requirements that would
enhance performance, but could be left out if necessary
– Out of scope: requirements that will not be included in the
project
23
 Cont…
• Once written, requirements need to be validated. It
is important to verify that the documented
requirements, assumptions and constraints match
those of the stakeholder.
– Models help users to visualize requirements
– Stakeholder review or walkthroughs can be used to
validate clarity and consistency as well as to ensure
stakeholder consensus on requirements
– Peer or supervisor review can be used to validate clarity,
consistency and that nothing has been omitted.

24
 Gathering existing documentation
• If you are writing documentation for an existing system,
program, network and/or application, some documentation
may already exist.
• You should consult any existing documentation that may
have accompanied the system (including technical
information). This could include:
– user guides
– project specifications
– online help
– procedure manuals.
• These documents will show you how the system, program,
network or application works. It should also show you what
the organisation’s work procedures are and how to apply
them.
25
 Using a user’s perspective

• The only way to find out how the system, program,

network or application works is to become a user so
that you become familiar with its features and you
are confident in using it.
• You should be looking at:
– the functionality — how it works
– the work processes surrounding its use — how the system
works with organisational processes and procedures.
• Another valuable source of information are staff
members who are already users or project team
members who have been working with the system.
26
 LO2 Designing Documentation
• This learning guide was developed to provide you the
necessary information regarding the following content
coverage and topics –
– Identifying Information requirements

– Creating document templates and style guides

– Conducting review of the system

– Extracting Content

– Developing the structure of the technical documentation

– Validating Technical documentation structure

27
 Writing effective user documentation
• As a confident user of the system you can begin to write the
documentation using the agreed template and relevant tools.
You will need a template for user documentation and the
relevant tools for development.

Planning content
• In the same way that you plan any piece of writing, you will
need to create a plan for writing the documentation. Before you
write the user documentation, write an outline of the contents.

28
 Cont…
• Organise the content into:
– Main headings
– Sub headings
– Points under each of the subheadings.
• It might be necessary to approach a subject matter
expert to assist with the planning or it might be
sufficient to use any existing documentation as a
model for the new documentation.

29
 Example
Organise the content Cont..
• Identifying and analyzing documentation needs
– Introduction to documentation
– Consulting Clients
• Internal departments

• External organizations

• Individual people

• Internal employees

30
 Reflect

• Think about the features that you have found useful

in documentation. What were they?

Tips for writing and designing effective user documentation

• Use this as a checklist for planning the features of

user documentation.

31
 Cont…
• When writing the content, it is important to follow effective writing
principles. Other features such as graphic design and navigation will
help user documentation work for users.
• Along with getting the content right, you’ll need to use sound
principles for layout and usability as well.
• A final stage in the development of your documentation will be testing
the documentation with real users, then revising the documentation
and testing it again.
• So you’ll have the opportunity to adjust content and other features to
better fit the needs of your target users.
32
 Content Features
• Give a brief introduction where you state the purpose and
objectives of the documentation.
• Include a table of contents or index.
• When writing, keep the users’ needs in mind, i.e put yourself
in the users’ place.
• Ensure the content is accurate.
• Make clear sections for different types of features/information.
• Break the content down into easy-to-digest ‘chunks’, e g using
paragraphs and sub headings, or multiple screens.

33
 Cont…
• Use illustrations, diagrams, charts and/or screen
shots where appropriate.
• State instructions clearly and step-by-step.
• Use plain English and avoid jargon.
• Use technical terms only where necessary.
• Include a troubleshooting or help section.
• Include a glossary of the technical terms you have
used.

34
 Layout features
• Make the document structure as simple as possible and logical
by providing cues to locate information.
• Ensure good usability, especially for online documentation.

• Cross-reference information, e g use hyperlinks in online

documentation.
• Warnings, comments and help should be well-organised and
visible.
• Aim for a clean design for text styles and layout that is
consistent across all pages.
35
 Involving business units in the development of
user documentation
• One of the reasons a project could fail is that people in the business units
who will be impacted by the project’s implementation have been left out of
the consultation process.
• From the beginning to end of a project, project team members need to work
closely with users. They are an invaluable resource for developing
documentation.
• Though users and subject matter experts from the business units might not
have the skills necessary to write effective documentation, they have the
content knowledge.
• If you can tap into this knowledge your content will be accurate and
relevant.
36
 Reflect
• What do you think may be the benefits of involving users
and accepting their feedback?
– The end product is more closely aligned with the needs of the users.
– The process of creating user documentation is much simpler due to
the expert knowledge users bring.
– Implementation and take-up of the new system, program, network
or application is much greater with user involvement, as the
subject matter experts can act as ‘champions’ within the business
units.

37
 Developer tools
• The writing tools you use will be determined by the
medium — paper-based or online. Tools (software)
can include applications for:
– word processing
– image editing
– image conversion (to web-ready)
– painting and drawing
– HTML conversion/authoring/editing
– FTP utility
– site management software

38
 Cont…
– multimedia or slide show authoring
– audio and video equipment and editing software.
– If you are developing paper-based materials, useful tools
are:
– word processing software, eg Microsoft Word
– imaging software, eg Adobe Photoshop and/or Adobe
Illustrator
– If your materials are going online, useful tools are:
– HTML conversion/authoring/editing
– imaging software, eg Adobe Photoshop or Fireworks
– FTP utility, eg FTP Pro or CuteFTP.

39
 Features of Template
Paper-based documentation
• Features that may be included in paper-based
documentation are:
– table of contents
– columns and tables
– page and section numbering
– headers and footers
– graphics and text surrounds
– substantially chunked information

40
 Online documentation
• Features that may be included in online
documentation are:
– table of contents hyperlinks
– tables
– links to other pages/sites
– navigation icons
– usability/functionality
– heavy use of graphics

41
 Obtaining sign-off on template
• Like all documentation, templates also need to be signed-off by the
relevant people. The sign off process will be outlined in the
organisational documentation policy.
• The content of the template will depend on the purpose of the
documentation. A template for training materials will look quite
different to a template for a procedural manual.
• The template should be designed in consultation with users or a
subject expert. Once the template has been designed, it should be
distributed according to the user documentation policy, or, the agreed
review process if you are working towards final sign-off.
42
Creating document template and style guides

• When developing a basic design for your documents

you will need to consider both their purpose and
their function.
• What information is being presented, how will the
documents be used, will they be provided in printed
form or will they be accessed online?

43
 Visual Style and Features of document
• What size and orientation will your document be—is a standard paper size like A4
or A3 appropriate or will you need to set a custom size; does your document layout
require a portrait or landscape orientation?

• Is colour an important feature of the document or is black on white a better choice

for printable documents.

• Colour, if used, can be chosen to suit the subject of the document; to add visual
contrast, formality or informality; or to identify the structure of your information
or highlight key concepts and important points.

• Will your document include any branding, labelling or copyright notices? Will you
need to break your document into sections—how do you retain the feel that it is the
same document?

44
 Main Heading
• Use the Heading 1 style for primary headings so that
screen readers can identify them as such.
• If not already, manually change your heading 1 style
to be:
– sans serif (e.g. Arial, Verdana, Trebuchet or Calibri),
– 16 pt, and
– Bold
– Then set this formatting as your default for this style.
45
 Sub Headings
• Use Heading 2 style for sub headings.

• If not already, manually change your heading 2 style to be:

– sans serif (e.g. Arial, Verdana, Trebuchet or Calibri),

– 14 pt, and

– Bold

– Then set this formatting as your default for this style.

46
 Sub (Sub Heading)
• Use Heading 3 for sub sub-headings.
• If not already, manually change your heading 2 style to be:
– sans serif (e.g. Arial, Verdana, Trebuchet or Calibri),
– 12 pt, and
– Bold
– Then set this formatting as your default for this style.

Paragraph
• Paragraphs should not be styled as headings. Paragraphs should be
‘normal’ style.
• They should be:
– Sans serif font, 12 point
– 1.5 spacing (except for lists of bullet points)
– Left aligned instead of justified
– Then set this formatting as your default for this style.
47
 Your document should also
• Leave sufficient white space at either side of the
page
• Avoid using block capitals or italics. Use bold to
make text stand out instead.
To amend default styles:
• Amend the style in line with the above guidelines then right click the
style in question under the home tab. Choose ‘modify’ from the drop
down list. This will open a box.

48
 Cont…
• Within the box, ensure that the style is formatted to
your preferences. For example, if ‘italics’ is checked,
uncheck it.

Choose the radio

button that states:
‘New documents
based on this
template’, and
click ‘okay’.

49
 To amend paragraph defaulting
• Left click ‘paragraph’ under the home tab.
• Ensure your alignment is set to ‘left’ and line spacing is set
to ‘1.5 lines’.
• Once your settings are correct click ‘default’.
• Click ‘yes’ on the resulting ‘Are your sure’ message.

50
 To test your new settings
• Open a new document and test each heading and paragraph style to
ensure all settings have been saved.

• Table Usage
• Construct tables to read logically from left to right, top to bottom order.

• Tables with column headings in the top row must have the top row
formatted as a header row. To set a table header row:
– Highlight the top row of the table

– Right click to display editing options

– Select “Table Properties” from the list

51
 Table properties
• The Table Properties window will be displayed;
click on the “Row” tab
• Check the option “Repeat as header at the top of
each page”

Col 1 Col 2 Col 3 Col 4

Row 1

52
 Images
• Alternative or Alt text is required for all images in a
document (excluding purely decorative images without
meaningful content).  
– Right-click on the image;
– Select Format Picture.
– The Format Picture dialog box will appear. Select the Web tab.
– In the Alternative text box, type in the description of the image.
– Click “OK”

53
 Conducting review of the system
• Document review (also known as doc review), in the
context of legal proceedings, is the process whereby
each party to a case sorts through and analyses the
documents and data they possess (and later the
documents and data supplied by their opponents
through discovery) to determine which are sensitive
or otherwise relevant to the case.

54
 Extracting Content
• Copyright is a legal right, existing in many
countries, that grants the creator of an original
work exclusive rights to determine whether, and
under what conditions, this original work may be
used by others

55
 LO3: Developing documentation
• This learning guide was developed to provide you
the necessary information regarding the following
content coverage and topics –
– Writing Technical documentation

– Translating technical terminology into plain English

– Applying Content format and style

56
 Writing Technical documentation
• Why write? In this age of telephone and tape
recorders, television and film, computers and
communication satellites, why should you bother
with writing?
• Writing is a way of thinking and learning. Writing
gives you unique opportunities to explore ideas and
acquire information.

57
Writing Technical documentation cont…

• Help you learn and gain authority over knowledge.

• Is a way of discovering, allows you to make un
expected connection among ideas and language.
• Writing create reading, create a permanent visible
record of your ideas for other to read and ponder.

58
Writing Technical documentation cont…

• Is powerfully means of communication ,for reading

informs and shape human thereby to create reading
for other people.
• Writing ability is needed by educated people. Your skill
with writing is often considered to reflect your level of
education. Most jobs today’s technological society
require writing skill for preparing documents ranging
from letter and means to formal reports
59
 Understanding the elements of writing

• Communicating: is writing means sending a

message that has a destination.
• The Message of writing is its content : Whether the
subject you write about is your choice or is assigned,
you must transform it into a message worthy of
communication.

60
Technical Writing

•Written text which addresses things like:

– What one has to do in order to accomplish something
– What is known about a particular topic

•People use technical writing when:

– They need to find out about a topic they know nothing
about
– They need to find out more about a topic they know a
little about
61
 Technical Writing cont…
•Two basic modes of using technical writing:
– Browsing; the reader flips through or reads through the pages,
hoping to get an overall idea of the content
– Searching: reader searches for a specific piece of information

•Technical writing should:

– Present material in a way that is easy for the reader to digest
– Organized material in order to help the reader find things easily

•Remember, the reader may not know anything about

the topic before reading it.
62
 Organizing a Technical Document
•It there is no structure to the document, every page looks like every
other page
– Browsers can’t see the relevance of what they are reading in the
context of the whole document
– Searchers can’t find what they are looking for easily.
•Techniques for organizing documents:
– Clear chapter names, section names, headings, subheadings,
paragraph headings (“units” of the document)
– Table of Contents
– Index
•Most word/text processor packages can produce these things for us automatically
– Still, tables of contents, etc. are so useful that they should be
produced by hand if necessary.

63
Some Guideline to write Technical Documentation

• Documentation should be from the point f view of the

reader
• Document should be unambiguous
• There should be no repetition
• Industry standards should be used
• Documents should always be updated
• Any outdated document should be phased out after due
recording of the phase out
64
 Individual Assignment

• Why is documentation important?

• How do you write good documentation?

• How do you share it with the right

people?

65
Example of Technical Documentation Organization

•Java in a Nutshell, David Flanagan, O’Reilly, 1997

•Table of Contents
– Preface
– Part I: Introducing Network architecture
• Gives tutorial introduction to network architecture for people more
familiar with network.
– Part II: Introducing network signal Transmission
• Describes features in network signal Transmission
– Part III: network Access methods
• Contains chapters on CSMA/CD, Token Passing, ,etc.
– Part IV: Networking Reference OSI
• Layer of OSI, and device that work in each layers.
– Part V: Quick Reference
• Chapters on each of the main packages
– Index
•Each Part contains 3 to 10 pages. 66
 Definitions
•Readers of technical writing don’t start out knowing the subject.
•All terms which user is not likely to know should be defined in the
document,
•Definitions can be either:
– “in-line”, that is inside the normal text
• E.g. “An Network Access method is a method that has no
body, only a signature definition followed by a semicolon”
– In a separate glossary section

67
 Definitions cont…
• A definition should:
– Use words that the user understands already
• E.g. the above definition of Network Access Method : good only if
reader already knows what a signature definition is
– Express clearly what distinguishes it from other related concepts
• E.g. that the method has no body
– Not be circular
• E.g. an Network access method is a method which is Accessing
Network
– Not just refer to what it is used for
• E.g. not “an Network access method allows different
implementations of the same method in subclasses
• Above is fine as part of an explanation, but not as a definition

68
 User Manual
•User Manual: Text intended to help the user of some product (software,
hardware, etc)
– Reader = User, User = Reader
•User manuals may have many purposes:
– Inform the user about how to use the product
– Sell the product
– Limit the company’s liability for the product
•User manuals that come with commercial software products are not the
greatest examples
– Sometimes seem to be included only because user expects them
– Companies rely on publishers of books to write good manuals,
tutorials.

69
 Material in a User Manual
•Generally two kinds of material appear in a user manual:
– Tutorial Material
• Text which teaches the user about the concepts needed to use the
product
• Instructions walking the user through details of how to do
specific tasks
– Reference Material
• Details of purpose and intended use of every individual button,
command, dial
• Declarations of individual functions in an API
•Usually both are necessary
– Facilities of product can usually be used in a variety of different ways
– Without tutorial material, user would have to piece together the overall
picture
– Without reference material, user would have trouble finding information on
specific topics
•Help facilities in program usually of the “reference” type
70
 Writing Tutorial Material
•Build reader’s knowledge from less to more
– Make section 1 to be material which doesn’t depend on anything
– Make section 2 that depends only on section 1
– Etc
•Go from specific to general or general to specific
– Use an example followed by / preceded by more general discussion
– Discuss a special kind of task (e.g. setting the VCR to record now),
then a more general task (e.g. setting the VCR to record at a
particular time) or vise versa
•Introduce each section, paragraph, etc. with something which
– Tells the reader what they are going to learn in the section
– Gives the reader any background information that they need to
know

71
 Example of Reference Manual Organization
•Hip Pocket Guide to HTML 4.01, E. Tittle, J.M. Stewart and
C. Valentine, IDG Books Worldwide, Inc, 2000
•Table of Contents
– Preface
– Chapter 1
• Gives a brief history and overview of HTML syntax
for novice Web page designers
– Chapter 2,3,4:
• Lists the categories of HTML tags, on which the
organizational scheme for Chapters 3-14 is based
• The standard sections that make up a tag definition
that is used in those chapters are also described
– Chapter 5-14:
• Tag definitions by category
– Chapter 15:
• Covers the use of the different standard characters
sets that can be displayed on a Web page using
HTML
– Appendices
• Tables of commonly used tools, attributes, colours
• Where to find extensions to HTML (plug-ins, applets)
• A list of the author’s favourite web tool software
packages
72
– Index
 Example of Reference Manual Organization

• There were other ways to organize this material

– E.g. tags could have simply been listed alphabetically
• The authors presumably chose this organization because:
– They intended the book for people who had some understanding
of what functions can be provided in a Web page (i.e. not Internet
illiterate!)
– … and to Web designers familiar with earlier versions of HTML
who need a tag reference guide that is well organized and up to
date.
• They kept the overview and tag summary brief, just giving the essentials
with very few examples
• However, each of the 91 tag definitions include a pertinent example…
– … and many of the category chapters give resource web sites in
their introductions

73
 Writing Reference Material
•Typically, consists of lots of little sections
– E.g. one for each tag, button, command, method etc
– Can be organized in a hierarchy of document units
•Present similar things in consistently similar ways
– E.g. description of an HTML tag:
• Heading with tag or tag pair and its name
• A brief definition of the tag, explaining purpose, function and effect on
document
• Definition and usage of each attribute that can be used to modify the
features of the tag
• A list of the contexts (i.e. other tag pairs) within which the tag can
legally appear
• Some style/usage tips
• An example of the use of the tag, with some attributes followed by a
screenshot
– Every tag would be described in this way
74
 Definitions in Reference Manuals
•Definitions can be given in a hierarchy where appropriate, e.g.
– “<table> … </table> Table: Creates a table. The table is
empty unless you create rows and cells using the <tr>, <td>
elements.”
– Table element tag descriptions are given immediately following the
table tag description
•Readers of technical writing who are knowledgeable don’t need to have
every term defined
•However, a definition should still:
– Use words that the reader understands already, i.e. general terms a
reader would already know from past experience or that have been
previously defined in the text, e.g.
• The above definition of the table tag is good only if reader
already knows what the other 3 tags do
• A list of tags covered with a brief definition of each is given at
the beginning of each chapter
• However, the terms table, row and cell are not defined since
they would already be familiar to anyone who has used a word
processor
75
Another Example from a Web Page:

76
 General Do’s and Don’ts
•Do use grammatical English
– Use spellcheckers
– You don’t have to have complete sentences all the time
– However, sentence fragments should be easy to read and unambiguous
•Do remember your audience
– Keep mentally checking whether the intended reader would really be
able to use what you have written.
•Do use a consistent writing style
– Don’t switch from first person to second person

77
 General Do’s and Don’ts
•Do use some kind of introduce for each unit of the document

– Introductory chapter for book, introductory paragraph for section,

brief description for command
– Should give the reader a summary of the whole unit and/or
background information they need to know
– Lets the reader see where the document is going

– Makes the material easier to digest once it is encountered

– Helps the reader find things later in the unit

•Use different fonts consistently (explain what they are)

78
 Validating Technical documentation structure
• Validation is the documented process of demonstrating that
a system or process meets a defined set of requirements.
• There are a common set of validation documents used to
provide this evidence.
• A validation project usually follows this process:
– Validation Planning – The decision is made to validate the system.
• A project lead is identified, and validation resources are
gathered.
– Requirement Gathering – System Requirements are identified.
• Requirements are documented in the appropriate
specifications. Specification documents are reviewed and
approved.
79
 Cont…
• System Testing – Testing Protocols are written,
reviewed, and approved. The protocol is executed to
document that the system meets all requirements.
• System Release – The Summary Report is written
and system is released to the end-users for use.
• Change Control – If changes need to be made after
validation is complete, Change Control ensures that
the system changes does not affect the system in
unexpected ways.

80
 General Validation Issues
• Validation Terminology
• Frequently Asked Questions about Validation
• Risk Assessment
• Testing Deviations
• Change Control for Validated Systems
Validation Documents: Requirements and Design
Specifications
– User Requirement Specification
– Functional Requirements
– Design Specification

81
 Validation Documents: Test Plans/Test Protocols

• Test Plans/Test Protocols

• Installation Qualification
• Operational Qualification

• Performance Qualification

82
Additional Validation Document Resources

• Validation Plans
• Traceability Matrix
• Validation Summary Report
• Computer System Validation
• Part 11 Training
• Auditing and Assessments

83
 What is Quality?
• The ongoing process of building and sustaining relationships by
assessing, anticipating, and fulfilling stated and implied needs.
• Quality is the customers' perception of the value of the
suppliers' work output. 
• A product or process that is Reliable, and that performs its
intended function is said to be a quality product.  
• Quality is nothing more or less than the perception the
customer has of you, your products, and your services!

84
 Quality Assurance

• Quality assurance (QA) is a way of

preventing mistakes and defects in
manufactured products and avoiding
problems when delivering solutions or
services to customers.

85
 The Difference Between QA and QC

•  Quality Control : A part of quality

management focused on fulfilling quality
requirements
• Quality Assurance : A part of quality
management focused on providing confidence
that quality requirements will be fulfilled”

86
 QA checklist
• A standard checklist should be used to check the documentation. A QA

checklist contains a list of standard formats and styles that reflect the

organisation’s user documentation standards.

• The purpose of the checklist is to ensure the documentation standards

are followed and that all user documentation is consistent in style and

appearance. Once the QA is complete, the documentation can be sent

for a formal review.

• The following table lists some of the criteria you could include in a QA

checklist.
87
Cont…

88
 Usability Testing
• Online user documentation requires a test for usability.
• This means that the interactive design and navigation should be
tested to see whether the user can easily find the information
they are after.
• It is preferable for usability testing to be performed by a
subject matter expert or a user (since they will be using the
documentation when it is finished).
• The organisation’s usability standards can be put into the QA
checklist.
89
 LO4 Evaluate and edit documentation
• At the end of these learning out come
the trainees shall able to know how to:
– Submitting technical documentation to
appropriate person
– Gathering and analyzing feedback
– Incorporating alterations
– Editing technical documentation
– Grammatical accuracy

90
 Submitting technical documentation to appropriate person

• How to submitting technical documentation?

• Three things are required for any technical review:
– Context (ie, an explanation of what is being requested
and why)
– The technical documentation itself (ie, objective evidence
to demonstrate compliance)
– Authorization to carry out the work.

91
 The submission should therefore contain at
least the following details:
• Certificate # reference(s);
• The type of review (new product, design change, shelf life extension,
etc);
• Brief product description, including model numbers involved, etc;
• Ref. for any other relevant submissions (for example, concurrent
applications which may affect the submission);
• An explanation of what has been submitted and how it demonstrates
compliance; and, for changes to existing certification:
• An explanation of
– what is affected (packaging, material change, sterilization, etc) and
• what is not affected (along with appropriate justification).

92
 Submission Method
• In order to facilitate faster reviews the following is
suggested:
– The preferred route for submissions is via the secure
document upload portal.
– Alternatively, documents may be submitted by email.
• This route is normally only feasible for small
submissions requiring relatively few documents of
small file size.
– We DO NOT need to receive a hard copy of the
information.
• If hardcopies are received in lieu of electronic files,
these will need to be converted to the format described
in section 4 below by our administration team. This
will add time and cost to the review. 93
 Document Format
• Language

• Electronic File Format

– Format and file size limits
– The preferred document format is PDF.
• However, it may be possible to accept the information
in any readily available software format including
Microsoft Word.

94
 Gather and analyze feedback
• Why Customer Feedback Is Important?
•  “What is the shortest word in the English language that
contains the letters: abcdefk?
• Answer: feedback. Don’t forget that feedback is one of the
essential elements of good communication.”
– Anonymous
–  Customers usually don’t bother to share feedback about an
experience that didn’t meet their expectations.
– Keep customer needs satisfactory experience in our product
95
 Cont…
• Why Customer Feedback Is Important? (Cont…)

– All customers are valuable to your business, but

some are more valuable than others! It is
important to understand the value of a customer

– “If you take care of your people, your people will

take care of your customers and your business
will take care of itself.”
96
 Cont…
• How to Get Quality Customer Feedback?
– Provide Proactive Live Chat Support
– Get Feedback on Live Chat Session
– Measure Your Customer Service Performance
– Call Your Customers Regularly
– Display Positive Customer Feedback
– Use negative feedback to showcase professionalism

97
 Cont…
• “We all need people who will give us feedback.
That’s how we improve.”
•  “Feedback is the breakfast of champions.”
– Ken Blanchard
• “Feedback is a gift. Ideas are the currency of our
next success. Let
people see you value both feedback and ideas.”
– Jim Trinka and Les Wallace
• “True intuitive expertise is learned from prolonged
experience with good feedback on mistakes.”
– Daniel Kahneman
98
 Cont…
• How to Get Quality Customer Feedback?
– 1. Provide Proactive Live Chat Support
• Chat support can help a company get closer to its
customers by better understanding their needs and
challenges.
• It also helps identify patterns if there are any
recurring issues and helps find long-term solutions for
those issues.
99
• How to Get Quality Customer Feedback?
– 2. Get Feedback on Live Chat Session
• Just like e-mail surveys, surveys which are sent after
you close a ticket in a customer support portal.

100
 Cont…
• 10 Tips to Improve Effective Customer
Feedback Analysis
– Analyze all feedback
– Categorize (and sub-categorize) feedback
– Use negative and positive feedback
– Look at root causes

101
 Cont…
• 10 Tips to Improve Effective Customer Feedback
Analysis
– Understand the value of the customer

– Look for trends

– Don’t compare unrelated data

– Consolidate results and determine a plan of action

– Alert the right teams and individuals within your organization

– Use automated tools to reduce your workload

102
10 Tips to Improve Effective Customer Feedback Analysis

• Analyze all feedback

– This may sound obvious, but it is vital that you actually
analyze all the feedback you get – otherwise why bother
collecting it in the first place!
– Whilst some feedback may give fairly standard or
unremarkable details (which will also be useful – see the
section below on trends), some may contain information that
could potentially be a major breakthrough for your business.

103
10 Tips to Improve Effective Customer Feedback Analysis

• Categorize (and sub-categorize) feedback

– You will find rapidly that feedback will start to fall into
more general categories
• These could include the speed of your service (or lack
of), accuracy, courtesy and helpfulness of particular
staff, price and choice of products, availability or
location etc.

– Sorting feedback into categories will immediately help to

show a wider picture of how the customer views your
business and services. Of course some customers may
comment on a number of categories and you can file these
accordingly.
104
10 Tips to Improve Effective Customer Feedback Analysis

• Use negative and positive feedback

– positive feedback, there is a direct positive
correlation between the concentration and the
process rate.
– One good example is how the endocrine system
regulates the release of its hormones.

105
10 Tips to Improve Effective Customer Feedback Analysis

• Use negative and positive feedback

– Negative feedback controls the process rate to
prevent substance accumulation.
– Contrary to positive feedback, it reflects a
negative correlation between the concentration
and process rate.
– Most homeostatic procedures involve negative
feedback as most mechanisms achieve
equilibrium by going back to their original states.

106
10 Tips to Improve Effective Customer Feedback Analysis

• Use negative and positive feedback

107
10 Tips to Improve Effective Customer Feedback Analysis

• Analyze all feedback

– This may sound obvious, but it is vital that you actually
analyze all the feedback you get – otherwise why bother
collecting it in the first place!
– Whilst some feedback may give fairly standard or
unremarkable details (which will also be useful – see the
section below on trends), some may contain information that
could potentially be a major breakthrough for your business.

108
 Best negative and positive quota
• Whatever you do, good or bad, people will always
have something negative to say!!!
• Train your mind to see the good in everything.
Positive is a choice the happiness of your life
depends on the quality of your thought
• Negative people are only happy when the bring you
down to their level
• I am thankfully for those difficult people in my life.
They have shown me exactly who I don’t want to be.

109
 Editing technical documentation
• Technical writing and editing skills are highly
associated with each other. 
• Effective editing will help make bad writing good and
good writing becomes even better.
• Experienced editing will catch both factual and
grammatical errors in copy before it is published,
preventing  embarrassment, additional costs, and
possible legal action.
110
 Editing technical documentation
• Step 1. Develop a mastery of the English language
– It is very important for technical editors to learn and
understand the basic rules of the language, such as
sentence structure, grammar, and punctuation.
– Technical editors also need to develop advanced skills
for editing the style and context of technical writing
work.

111
 Cont…
• Step 2. Know the purpose of the work you are
editing
– Technical editors need to define the goal of a writing
work or the nature of its content in order to determine
what kind of audience the writing is trying to focus on.
– Once the editors understand the purpose of the writing,
they will be able to correct problems and help technical
writers create sharp-looking documents.

112
 Cont…
• Step 3. Familiarize yourself with the necessary style
– Each type of technical writing has different standards
and expectations that the piece must conform to. For
example, user manuals such as hardware guides, software
guides, and product operational manuals are written in
an instructional style.
– These documents teach users how to operate technical
products.

113
 Cont…
– Informative materials such as scientific testing reports,
annual reports, and organizational manuals are produced in
a factual style.
– They provide information of function on products or
organizations to the public.
– Promotional materials such as advertising flyers, product
campaign pamphlets, and marketing brochures are designed
in a commercial style. They help the sales department of a
corporation promote and sell its products and services.
114
 Cont…
• Step 4. Have the confidence to spot and fix errors
– An experienced technical editor should have the
judgment to search not only for syntax errors, but also
for logical mistakes, and to fix them in a correct way.
– Many companies use technical documents to market their
technologies; any illogical error in the content will cause
negative effects to these companies. Good editors will
help the organizations increase their profits.

115
 Cont…
• Step 5. Give yourself time to do the job right
– Rushing to edit a piece of writing work will cause missed
errors and make the document look unprofessional.
Technical editing experts have provided several
guidelines to create a sharp-looking document.
– They include putting away writing for a day, reading it
out loud, using text-to-speak program, building a
checklist of writers’ most common mistakes, customizing
spell check, and reading back to front, bottom to top,
116
right to left.
 Cont…
• Step 6. Read it through once for comprehension
– Technical content always contains vital information on
technologies and other important technical elements.
– Technical editors should read documents carefully before
start editing to understand all important information.
– This will lead the editing process in a positive direction
and avoid major editing flaws.

117
 Cont….
• Step 7. Re-read each sentence individually, making
corrections as needed
– Editors should make sure a sentence states its meaning clearly,
using the right words, and ensure that the sentence is in the
right place in the paragraph.
– They need to eliminate redundancy by deleting duplicate or
unnecessary words, sentences, and paragraphs. Also they
should check relevant facts and correct misspellings, syntax
errors, incorrect punctuation, and superfluous emphasis.
118
 Cont…
• Step 8. Review the work again by paragraph or
section
– Technical editors should ensure the clarity of a writing
work by reviewing the content thoroughly.
– A well-edited document will help the audience locate
technical information from paragraphs or sections
without difficulty.

119
 Cont…
• Step 9. Run an electronic spell check
– Technical editors should use the spell check to catch typo
errors that they may have missed. An electronic spell
check will be able to catch misspelled words, but it cannot
catch correctly spelled words used incorrectly.
– These guidelines provide great value to editors to help
improve their editing skills. Technical editors and writers
should work together to produce well polished documents
that will assist corporations to market their products and
also will help the audience learn about today’s new
technologies.

120
 The review process of documentation

• The review process varies from organisation

to organisation and project to project.
• The review process is generally outlined in
the organisation’s policy or the project
documents. It may be called something like
‘change control’.

121
A basic process is shown in the following
table:

122
 Documentation sign off
• Once the documentation has been reviewed and all of the
reviewers are happy with it, you can send it to the relevant
people for sign off.
• Who signs off?
• The project brief or other document that initiates the system,
program, network and/or application development or upgrade
will generally list the project and business unit stakeholders
who are responsible for sign off on all of the deliverables,
including documentation.
123
 Cont…
• These people will include the:
– project owner
– business unit managers where the system, program,
network or application is being implemented
– project manager
– other key stakeholders in support roles such as trainers,
human resource officers and change managers.

124
 Grammatical accuracy
• Grammar
• The sentence is the basic unit of academic writing.
This may seem obvious, but in informal spoken
English, people often use incomplete sentences.
Sentences in essays and assignments must always be
complete
• Complete sentence:
• The doctor saw the patient. Incomplete sentence:
– Seeing the patient.

125
• A complete sentence is a complete thought and
always has (at least) two components: a subject and
a predicate.
• The subject is the person or thing at the centre of
attention; the predicate tells the reader something
about the subject.

The doctor saw the patient.

subject predicate

126
 Cont…
• A paragraph is a collection of two or more
sentences developing a single topic, theme, or
idea. All the sentences in a paragraph should
thus be related in some way, and tell the
reader something more about the key idea.
• Syntax is the technical term for the rules
governing the way words in any language are
put together into sentences

127
Thank You

?
Have a nice
time!
128