Mary Help College

Department of Information Technology

Level III

Unit of Competence :-
Create Technical Documentation
LO2 :- Design 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.
LO2 :- Design Documentation

Types of user documentation

 There are different types of documentation that can
be available for each computer application, for
example:
1. User Manual/Guide
2. Technical Manual/Guide
3. Training Manual/Resources.
LO2 :- Design Documentation

 When software is purchased it usually comes with a

user guide and technical guide.
 Training resources are then either purchased or
developed in-house.
 When computer applications are developed internally,
a user guide, technical guide and training resources are
usually developed to support the application.
LO2 :- Design Documentation

 A User Guide shows the user:

 How to use the application, i.e. the steps required
to complete various tasks
 Screens dumps with ‘tips’ data to give the user a
complete picture of how to enter data and process
the data
 Tutorials.
LO2 :- Design Documentation

 The Technical Manual generally contains the

technical information such as:
 System requirements to run the application
 How to install the application
 Configuring the application
 How to get technical support.
LO2 :- Design Documentation

 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.
LO2 :- Design Documentation

 Organise the content into:

 Main headings
 Sub headings
 Points under each of the subheadings.
LO2 :- Design Documentation
 Tips for writing and designing effective user documentation
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.
LO2 :- Design Documentation

 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.
 Include a glossary of the technical terms you
have used.
LO2 :- Design Documentation

Layout features
 Make the document structure as simple as possible and
logical by providing hints 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.
LO2 :- Design Documentation

Developer tools
 The writing tools you use will be determined
by the medium:
1. Online.
2. Paper-based
LO2 :- Design Documentation

 If you are developing paper-based materials, useful

tools are:
 word processing software, e.g. Microsoft Word
 imaging software, e.g. Adobe Photoshop and/or
 Adobe Illustrator.

 If your materials are going online, useful tools are:

 HTML conversion/authoring/editing
 imaging software, e.g. Adobe Photoshop or Fireworks
 FTP utility.
LO2 :- Design Documentation

Quality assurance (QA)

 Once the documentation has been written, a
quality assurance check should be conducted
before the draft is sent out for evaluation.
 This check is best done by a subject matter expert,
another member of the project team or a different
writer.
LO2 :- Design Documentation

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
evaluation.
 LO2 :- Design Documentation

Table 1: QA checklist

Criteria Evidence to look for

 Is the medium  Consider work performs, frequency of
suitable? updates.

 Are the purpose  Objectives specified

and objectives  Outcomes measurable
clear?  Achievable given the stated skill level of
future users
 LO2 :- Design Documentation

Table 1: QA checklist
Criteria Evidence to look for

 Is the documentation  Plain language

suitable for the intended  Terms explained
audience?  User-centred

 Is the skill level of the  skills required to understand

user stated? and perform tasks specified
 LO2 :- Design Documentation

Table 1: QA checklist
Criteria Evidence to look for
 Is the content  Clear sections
complete and well  Pages/screens numbered
organised?  Summaries included
 Content matches objectives
 LO2 :- Design Documentation

Table 1: QA checklist
Criteria Evidence to look for
 Is it easy to access Access points include:
and navigate the  table of contents
information?  well-developed index with
accurate matches
 cross referencing
 hot spots (online)
 glossary
 legend to explain any symbols.
 LO2 :- Design Documentation

Table 1: QA checklist
Criteria Evidence to look for

 Are instructions  one task in one instruction

clear?  instructions are numbered
 technical jargon avoided, explained
where necessary, and located in the
glossary.
 LO2 :- Design Documentation

Table 1: QA checklist
Criteria Evidence to look for
 Logical flow of  Topics build on the previous topic
information and increase in level of difficulty.
 Ease of use  users can find what they are
looking for
 users understand it
 users believe it is complete and
accurate
 LO2 :- Design Documentation

Table 1: QA checklist
Criteria Evidence to look for
 Consistency
layout in  heading styles used
consistently
 consistent use of fonts, type
and size for both headings and
body text
 font types limited to two or
three consistent use of colour,
paragraph styles, etc.
 LO2 :- Design Documentation

Table 1: QA checklist

Criteria Evidence to look for

 Balance of text and  Adequate use of white

white space. space
 Information is easy to read
and follow
 left justification been used
 LO2 :- Design Documentation

Table 1: QA checklist
Criteria Evidence to look for

 Visual  adequate use of tables,

indications. illustrations, colour and other
visual elements
 different kinds of information
are clearly identified for easy
reading.
 LO2 :- Design Documentation

Table 1: QA checklist
Criteria Evidence to look for
 Visual indications.  instructions for user to
perform a task at the
computer
 explanations of tasks
 Warnings
 comments to the user
 shortcuts to functions:
function keys
 LO2 :- Design Documentation

Table 1: QA checklist
Criteria Evidence to look for

 Presentation  Document looks interesting

to read
LO2 :- Design Documentation

 Remember these four elements of good

page and document design:
 Proximity
 Alignment
 Repetition
 Contrast
LO2 :- Design Documentation

Proximity
Group related items together
LO2 :- Design Documentation

Alignment
Every item should have a visual
connection with something else on
the page.

Don’t place anything on the page

randomly.
LO2 :- Design Documentation

Repetition
 Repeat some aspect of the design
throughout the entire piece.
 headers
 footers
 lines
 bullets
LO2 :- Design Documentation

Contrast
If two items are not the same,
then make them different.

Really different.
 LO2 :- Design Documentation

Design Document
 Visual Elements of a Page text text text text
text text text text
 Text
text text text text
 Headings and titles
 Graphics
 Simple separators like
lines and boxes
 Headers and footers
 White space
LO2 :- Design Documentation

White Space: A Design Element

 Use white space to set off important or “different”
items:
 figures and tables (including titles)
 titles
 headings and (some) subheadings

 Follow conventions for margins and line spacing.

 LO2 :- Design Documentation

Design of Headings
 Indicate level of heading (major heading,
subheading, etc.).
 Be consistent with design of each level
 Consider making differences more projecting than
you might at first think.
 Theses and dissertations follow discipline
conventions (often, numbering).
LO2 :- Design Documentation

Use size and position to differentiate

Title
Heading Level One
Heading level two
Heading level three. Might be run on with text. If you
use numbering, do not use bullets.
LO2 :- Design Documentation

Use numbering to differentiate

1. Heading One
1.1 Heading Two
1.1.1 Heading Three

You don’t have to use different size or other

differentiation as well, but you may.

Try not to use more than a three-point system.

e.g., 3.1.2
 LO2 :- Design Documentation

Use fonts and styles to differentiate

Heading One
Heading Two
Heading Three. Helps to differentiate from body text.
Don’t use bullets with headings.

You may use one style for headings, another for

body text:
Introduction
This is the introduction. Blah, blah, blah.
LO2 :- Design Documentation

Bullets
 Use for lists within paragraphs.
 Use bullets carefully – don’t
overuse.
 Use when all elements in list are
equally important and have no special
rank, sequence, or significance.
 Consider using when listed items are
long (more than one line) but are not
prioritized.
LO2 :- Design Documentation

Designing Pages: A few Tips

 Use same design for all pages
that contain same kinds of
information.
 Use limited variety of easy-to-
read typefaces.
 Ragged right margin is slightly
easier to read for long documents
than are fully justified margins.
 ALL CAPS ARE HARD TO
READ -- USE SPARINGLY.
 LO2 :- Design Documentation

Tips
 Find out whether your organization has a style guide --
use it!
 Team or co-authors producing a document need to create
style guide if one does not already exist.
 For journal papers or conference proceedings, check
Information for Contributors or Call for Papers for style
guidelines.
 LO2 :- Design Documentation

Style Sheet Checklist

 Document  Page Numbering
 Paper and covers  Where on page?

 Single-sided?  What font/type?

 Margins  Different for different sections?
 Sections  Tables and Figures
 Start on right-facing pages?  Integrated with text??

 Use line or other graphic device?  Where do labels go??

 Headings and Subheadings  References

 Position  Citations in parentheses in text?

 Font & size & characteristics  Reference list goes where?

 Main Text  Abbreviations, Acronyms, Equations

 Font  Include glossary? Where?

 Paragraph indentation?  Acronyms spelled out where?

 Line spacing  Mathematical variables explained where?

LO2 :- Design Documentation
 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.
LO2 :- Design Documentation
 Summary
 This reading has covered the knowledge and skills
required to write user documentation for a new or
upgraded system, program, network or application
implementation. We began with ways of reviewing
the existing system, program, network or application.
 Then we looked at elements for writing and
designing effective user documentation and the range
of tools available. Documentation is completed after
a quality assurance check and usability testing which
ensure that standards are met.