Ariket tvet college
Hardware and Network Servicing
NTQF Level III
Unit of Competence: Create Technical
Documentation
Module Title: Creating Technical
Documentation
LG Code: ICT HNS3 M04 LO2-12
TTLM Code: ICT HNS3 TTLM 0214v2
1
Learning Guide for HNS LEVEL III Author: ICT DPT
LO2: Designing Documentation
Instruction Sheet Learning Guide #12
This information sheet will help you to design technical documentation.
This learning guide is developed to provide you the necessary information regarding the
following content coverage and topics
Identify information requirements
Create document templates and style guide
Review the system in order to understand its Functionality
Extract content that meets information requirements
Develop structure of technical documentation
Validate technical documentation structure with the client
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
Identify information requirements
Create document templates and style guide
Review the system in order to understand its Functionality
Extract content that meets information requirements
Develop structure of technical documentation
Validate technical documentation structure with the client
Learning Instructions:
1. Read the specific objectives of this Learning Guide.
2. Follow the instructions described carefully.
3. Read the information written in the “Information Sheets 1”. Try to understand what are
being discussed. Ask you teacher for assistance if you have hard time understanding
them.
4. Accomplish the “Self-check 1” in page __.
5. Ask from your teacher the key to correction (key answers) or you can request your
teacher to correct your work. (You are to get the key answer only after you finished an-
swering the Self-check 1).
2
Learning Guide for HNS LEVEL III Author: ICT DPT
Information sheet-1 LG12
Design documentation
Identify information requirements
Requirements are the description of what particular hardware or software does or shall do. It is
used throughout development to communicate what the hardware or software does or shall do. It
is also used as an agreement or as the foundation for agreement on what the software shall do.
Requirements are produced and consumed by everyone involved in the production of documen-
tation: end users, customers, product managers, project managers, sales, marketing, software ar-
chitects, usability engineers, interaction designers, developers, and testers, to name a few. Thus,
requirements documentation has many different purposes.
Requirements come in a variety of styles, notations and formality. Requirements can be goal-like
(e.g., distributed work environment), close to design (e.g., builds can be started by right-clicking
a configuration file and select the 'build' function), and anything in between. They can be speci-
fied as statements in natural language, as drawn figures, as detailed mathematical formulas, and
as a combination of them all.
The variation and complexity of requirements documentation makes it a proven challenge. Re-
quirements may be implicit and hard to uncover. It is difficult to know exactly how much and
what kind of documentation is needed and how much can be left to the architecture and design
documentation, and it is difficult to know how to document requirements considering the variety
of people that shall read and use the documentation. Thus, requirements documentation is often
incomplete (or non-existent). Without proper requirements documentation, software changes be-
come more difficult—and therefore more error prone (decreased software quality) and time-con-
suming (expensive).
The need for requirements documentation is typically related to the complexity of the product,
the impact of the product, and the life expectancy of the software. If the software is very com-
plex or developed by many people (e.g., mobile phone software), requirements can help to better
communicate what to achieve. If the software is safety-critical and can have negative impact on
human life (e.g., nuclear power systems, medical equipment), more formal requirements docu-
mentation is often required. If the software is expected to live for only a month or two (e.g., very
small mobile phone applications developed specifically for a certain campaign) very little re-
quirements documentation may be needed. If the software is a first release that is later built upon,
requirements documentation is very helpful when managing the change of the software and veri-
fying that nothing has been broken in the software when it is modified.
3
Learning Guide for HNS LEVEL III Author: ICT DPT
Traditionally, requirements are specified in requirements documents (e.g. using word processing
applications and spreadsheet applications). To manage the increased complexity and changing
nature of requirements documentation (and software documentation in general), database-centric
systems and special-purpose requirements management tools are advocated.
Create document templates and style guide
Designing templates
Once you have determined the documentation requirements, you can develop a template that
meets those requirements and makes the job easier. A template is a file that contains a standard
layout, styles and fonts that are used in the production of the documentation.
When you want to create a file for user documentation, you open the standard template, usually
in Word, and the layout, fonts and styles are already set up in the document. All you need to do
is start writing. Everyone uses the same template, so there is a consistent look and feel to all of
the user documentation.
The template may be:
a Word template
an HTML template
an online help template.
The medium will determine what kind of template you use.
Features of templates
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.
Online documentation
Features that may be included in online documentation are:
table of contents hyperlinks
tables
links to other pages/sites
navigation icons
4
Learning Guide for HNS LEVEL III Author: ICT DPT
usability/functionality
heavy use of graphics.
Obtaining sign-off on templates
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 tem-
plate 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.
Develop structure of technical documentation
Step 1 - Assess the purpose of the documentation
Begin the documentation process by assessing the purpose of the document. Different documents
serve different purposes. For example user guides inform a products users how to best use a
product and get the most from it, while a sales presentation's purpose is to get the reader to buy a
product. It is important to establish what you want the document to achieve, as this will influence
the rest of the documentation process.
Step 2 - Assess what tasks the users will perform
This step involves assessing the tasks users will perform, this is known as a task oriented ap-
proach. The task oriented approach begins by focusing on how the users would use the software
or product to solve their problems or complete real world tasks.
The task-oriented approach creates more useful documentation than the functional approach to
document development, which involves describing each button and function. The problem, with
the functional approach is that it only gives the user half the story and does not help to integrate
the software or product with real world tasks that the user will need to perform. This can often
leave users with a low opinion of the software or product, when it was really the documentation
that let them down.
At the end of this stage you will have a list of tasks and sub-tasks that will provide a skeleton for
the documentation.
Step 3 - Analyse the audience
The audience analysis is where you create a profile that provides generic information and any as-
sumptions you are making about the different audiences groups the document will have. Work-
ing from the audience analysis helps you to tailor the documentation as closely as possible to the
needs of the reader. The audience analysis is where you try to understand who will be using the
product you are documenting and what assumptions you can make about the knowledge and
5
Learning Guide for HNS LEVEL III Author: ICT DPT
skills they possess. This allows you to include the appropriate level of detail and write using lan-
guage that each audience group will understand.
Step 4 - Develop an audience task matrix
The audience task matrix links the tasks to the different audiences that a document is likely to
have. The audience task matrix provides a useful tool for structuring the documentation, group-
ing information by likely audience and if required, helping us split a document that was too
large. It also provides an additional check that all users and tasks have been considered.
Step 5 - Create the document plans
The next step is to create the document plans based of the information from the previous steps.
This is a top down process, which you start by creating a high-level table of contents. Then you
loop between the document plan and information gathering until you feel you have all the re-
quired content for each section.
Step 6 - Gather information
The information gathering process involves a combination of interviewing Subject Matter Ex-
perts (SMEs) and working from existing documentation. For example, when documenting soft-
ware there is often valuable information in requirement specifications, functional specifications
and use case documentation. This provides a basic level of information that you can build on
through interviewing the SMEs.
Step 7 - Design the look and feel of the document
Designing the look and feel of the document involves deciding what format to use. For many
projects a paper document may not be the best choice, an online help system or a web page may
provide a better solution. It is important that the document looks good and is easy to read, so you
need to consider the page layout, use of white space and visual density. You also need to take
into account navigation features, so that multiple users can navigate through the document in dif-
ferent ways. At this stage you must also check if there are corporate guidelines or style guides
that the document needs to adhere to.
Step 8 - Begin the writing process
Now you have a good idea of the content and a template to work with you can begin the writing
process. During the writing process you focus on presenting information consistently, separating
procedural information and reference material, determine the most effective use of images and
diagrams, and making sure the information is tailored to the appropriate audience.
Step 9 - Edit and proofread the documentation
Finally you edit and proofread the documentation. You check each document against a proof-
reading checklist. If there is a style guide for the documentation then base the checklist on the
6
Learning Guide for HNS LEVEL III Author: ICT DPT
style guide. This is an iterative process where the sentence structure and clarity of the document
improves with each pass.
7
Learning Guide for HNS LEVEL III Author: ICT DPT
Self-Check-1 Written Test
Name________________________ Date________________________
Directions: Choose the best answer from the given alternatives
1. Technical manual contains the technical information about_________
a. system requirements to run the application
b. how to install the application
c. configuring the application
d. How to get technical support
e. All
f. none
2. Before you write the user documentation you have to point out____________
a. outline of the contents
b. main headings
c. sub headings
d. Points under each of the subheadings.
e. All
f. None
3. To write effective user documentation you have to______________
a. Plan the content
b. Gather important information
c. Getting advice from important person
d. All
e. none
4. Which one of the following is important for writing and designing effective user
documentation_____________
a. Give a brief introduction where you state
b. Briefly explaining about the purpose and objectives of the documentation.
c. Include a table of contents or index.
d. When writing, keep the users’ needs
e. All
f. None
8
Learning Guide for HNS LEVEL III Author: ICT DPT
5. A user guide shows the user___________________________
a. How to use the application
b. Screens dumps with ‘dummy’ data to give the user a complete picture of how to enter
data and process the data
c. A and B
d. All
e. None
6. Which one of the following is not important for writing and designing effective user
documentation_____________
a. Ensure the content is accurate.
b. Make clear sections for different types of features/information.
c. Break the content down into easy-to-digest
d. All
e. None
7. Which of the following is the most important for writing user documentation?
a. Use illustrations, diagrams, charts and/or
b. State instructions clearly and step-by-step.
c. Use plain English and avoid jargon.
d. Use technical terms only where necessary.
e. All
f. None
8. Which one of the following developer’s tools is not used to create online documentation?
a. HTML conversion/authoring/ c. FTP utility.
editing d. Word processing software
b. imaging software, eg Adobe e. All
Photoshop or Fireworks f. None
9. Which one of the following is true about Quality assurance?
a. It should be used to check usefulness of the documentation.
b. It contains a list of standard formats and styles.
c. It is to ensure the documentation standards are followed.
d. All
e. None
10. Which one of the following Quality assurance checklist is used to check the font type, text style?
a. Consistency in layout d. All
b. Logical flow of information e. None
c. Ease of use
11. Which one of the following is different from the other?
a. user manual/guide d. Developer Tools.
b. technical manual/guide e. All.
c. Training manual/resources.
9
Learning Guide for HNS LEVEL III Author: ICT DPT
Operation Sheet Analyze documentation
Name____________________________________
Date______________________________
LAP Test Practical Demonstration
Name: _____________________________ Date: ________________________
Time started: ________________________ Time finished: _________________
Instructions: Given necessary templates, workshop, tools and materials you are
required to perform the following tasks within 2 hours.
10
Learning Guide for HNS LEVEL III Author: ICT DPT