Transcript Document

Best Practices
Chapter 8 - Documentation
Agenda











2
Types of Documentation
Why Some Documentation Fails
Characteristics of Effective Documentation
Steps for Creating Documentation
Designing the Documentation
Writing the Documentation
Editing the Documentation
Creating the Index
Online Documentation
Publishing Project Documents Online
Further Principles and Practices
Types of Documentation

Documentation is one of the most important parts of a software system. It
can serve several purposes (Britton & Doake, 2003):





Documentation can be classified as:


3
Enables developers understand how the system has been built, so that it can
be maintained and modified if necessary.
Offers instructions for the day-to-day operation of the system.
Introduces new users to the system and allows them to find their way around.
Provides information that enables experienced users to exploit the system to
its full potential.
Internal documentation: produced for in-house use E.G.  programmer
manual
External documentation: produced for outside use E.G.  user manual.
External documentation is often used as a marketing tool to help sell a
product therefore it is produced to a higher standard than internal
documentation.
Types of Documentation
(cont)

Developer Documentation



Aimed at developers who maintain and modify a system.
Should provide a complete record of the system development process, from the initial
request to the implementation and testing of the system.
Examples of developer documentation:
•
The systems manual::
•
•
•
•
•
•
•
•
•
•
•
The programmer manual:
•
•
•
•

4
The problem definition
Descriptions of the system design
Details of the hardware and software used
JAD minutes
Use case diagrams
Use case narratives
Entity relationship diagrams
System design models
A data dictionary
A Gantt chart
Overview layout of the system E.G.  by function or according to the menus
Description of each function, including the commented code for each one.
Explanation of each form and each field/control that it contains.
Set of test plans, test data and test results for the system.
The developer documentation should show what was done, how it was done and why it
was done that way
Types of Documentation
(cont)

Operations Documentation



Focus is on day-to-day running of a system E.G.  making backups etc …
System size and complexity and expertise of the people who will perform the operating
tasks determine the style and content of the documentation.
User Documentation



Aimed at assisting the users in using the system effectively.
Must be easy to use and understand and be constructed as a reference document with all
the necessary tools to help the user find the information he or she might look for.
Two categories of user documentation:
•
Documentation aimed at novice users: Concentrates on enabling them to get started, perform
basic tasks, gain confidence with simple operations and get out of trouble quickly and easily:
•
•
•
•
•
•
•
•
5
An introduction to the system
The system requirements
The installation procedure
A system tutorial
Descriptions of error messages and how to respond to them
Descriptions and examples of reports and queries
A glossary of technical terms
Documentation aimed at experienced users: Enables them to take advantage of short cuts and
more advanced features of the system.
Types of Documentation
(cont)

Other Types of Documentation






6
Animated or dynamic tutorial materials on CD-ROMs, DVDs, or videotapes
Novice users may welcome quick-reference cards that contain answers to the
common questions.
All documentation must be designed and written for its intended audience.
E.G.  the primary focus of a user reference manual  information needed
must be located quickly and with ease. The secondary focus  information
should be understandable, accurate, and up to date.
E.G.  The primary focus of a systems maintenance manual  ensuring
that information is complete, accurate, and up to date. The secondary focus
 making the information easy to locate and understand.
When multiple types of users E.G.  a computer user and a manager use
certain documentation, writers must take into account the differences
between the users and prepare the documentation in such a way that it
caters for their individual needs.
Why Some Documentation
Fails





7
Documentation that does not serve its
purpose effectively is a failure.
E.G.  ineffective documentation decreases
productivity, reduce efficiency and waste
resources.
Also increases training costs.
Documentation that is difficult to understand
or use may be rejected by users.
This can cause negative feelings amongst
users when future documentation or systems
are released.
Why Some Documentation
Fails (cont)

Reasons why documentation might fail (Crown, 1992):

User attitudes: Users might reject the documentation because:
•
•
•
•
•
•

Management attitudes: Management might contribute to the failure of documentation::
•
•
•
•

They might not allow for enough time to write the documentation.
They might not acknowledge the value of documentation.
They might not have clearly defined the scope and the design of the system and this is reflected in
the documentation.
They might impose a limited budget requiring that a single manual serve too many audiences and
accomplish too much.
Writer attitudes: The writer may be the cause of the failure because:
•
•
•
8
They cannot find the information they want and therefore give up.
They cannot understand the information they have found.
They realize that the information is out of date.
They are too lazy to look for the information.
The documentation is too thick.
The documentation is difficult to access (for example, the only copy of a manual might be locked in a
supervisor’s office).
He or she does not spend enough time understanding the system before starting to write the
documentation.
He or she is more concerned about the look and design of the manual and not the manual’s content.
He or she fails to clarify statements that could be misunderstood.
Characteristics of
Effective Documentation


Effective documentation is documentation that is actually used by its
users.
Five specific characteristics of effective documentation:






9
Available: The documentation must be available in a form and place
whereby users can refer to it when necessary.
Easy to use: The documentation must be a pleasure to use and the
information in it must be easy to find.
Easy to understand: Information in the documentation must be easy to
understand.
Up to date: The documentation must be up to date, reflecting latest changes
and revisions to the system.
Reliable and convincing: The information must be reliable and convincing.
Effective documentation also looks attractive, is well designed, and is well
produced. Unattractive or unprofessional documentation might be rejected
by users before they even attempt to use it.
Characteristics of Effective
Documentation (cont)

Heckel’s (1992) thirty central principles for designing friendly
software were discussed in the chapter 4 (Usability and
User Interface Design), many of these can be applied to
creating effective documentat ion:

Know your subject:
• Before you write effective documentation you must understand
what you are writing about. E.G.  when writing a user manual
for an application, be sure that you know how the application
works.

Know your audience:
•
•
•
•
•
•
•
10
“Who are my users?”
“What is important to them?”
“How do they think?”
“Why are they using the software?”
“What do they know?”
“What don’ t they know?”
“What are their expectations?
Characteristics of Effective
Documentation (cont)

Maintain the user’s interest:


Communicate visually:


Focus his or her attention on what is important, and do not present more information that the reader needs.
Anticipate problems in user understanding:

11
To allow readers to draw upon their existing knowledge and understanding and apply it to the content that
you are communicating.
Focus the user’s attention:


Avoid using language, terms, concepts, etc that the reader will not understand. Use simple and natural
dialogue that readers will be familiar with.
Communicate with metaphors:


Determine what the reader knows and lever that knowledge by speaking their language, using metaphors
that they are familiar with, and by using a consistent documentation design.
Speak the user’s language:


Structure documentation in a way that the user will be able to form a visual image of its structure? Evaluate
all images that will be painted in the minds of the readers to ensure that they aid their thought processes.
Make use of visual images: graphics, diagrams, illustrations, icons and screenshots, to help convey your
message.
Lever the user’s knowledge:


Interest can be stimulated in various ways: using colour, graphics and illustrations, and featuring interesting
and useful information.
Question how a reader will perceive the content of your documentation. Will they see it in the way you
intended? Aim to anticipate and eliminate potential misunderstandings.
Characteristics of Effective
Documentation (cont)

Reduce the user’s defensiveness:


Support the problem-solving process:


By the time the user has picked up your documentation he or she is
probably already feeling frustrated. Be sure that you support the
reader’s goals by helping the reader find what he or she is looking
for as easily and as quickly as possible.
Help the user cope:

12
Does the user manual make it simple for a reader to find a solution
to a problem he or she has encountered while using the
application?
Avoid frustrating the user:


Do not make a reader feel confused, helpless, frustrated or angry,
and do not be judgmental.
Provide users with information that describes their problems and
helps them solve them. Answer their questions and address their
concerns.
Characteristics of Effective
Documentation (cont)

Orient the user in the world:


Structure the user interface:


Can developers rely on a systems manual to contain an up-to-date entity
relationship diagram if they need it? Can users rely on an up-to-date user
manual to help them answer their questions or to help get them out of a
trouble spot?
Serve both the novice and the experienced user:

13
Organize the documentation logically making sure that its structure is
communicated to the mind of the reader. E.G.  a user manual’s content
should be structured in a way that the reader will find logical and not
necessarily according to the internal mechanics of the application it pertains
to.
Make your product reliable:


Don’t allow the user to get lost in the documentation. Give readers the means
to orient themselves, E.G.  by having page headers that include a
meaningful chapter title, page numbers and meaningful sections titles. Offer
directions to related content that may be of further assistance or benefit.
When there is a chance that the documentation will be used by readers of
varying skill and knowledge levels, be sure to design the documentation to
cater for all these potential readers.
Characteristics of Effective
Documentation (cont)

Develop and maintain user rapport:


Consider the first impression:


Be cautious of oversimplifying as this might make the documentation less
useful.
You need a vision:

14
Good documentation design is simple and economical, making it as easy as
possible to use and understand.
But not too simple:


The documentation should reinforce the mental model that an application has
built up in the user’s mind otherwise confusion can result.
Make your design simple:


The reader’s first impression is important for getting him or her to accept and
use an item of documentation.
Build a model in the user’s mind:


Get close to the readers and meet them at their level. You will then be in a
better position to lead them in the direction you want them to go.
The documentation writer’s vision for a software product’s documentation
should be congruent with the developer’s vision for the software product.
Steps for Creating
Documentation
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
15
Decide on a name for the documentation
Clearly define the purpose of the documentation
Define your intended audience
Gather the necessary information
Design the documentation
Design the table of contents
Write the documentation
Edit the documentation
Proofread the documentation
Create the index
Produce the documentation
Maintain the documentation
Steps for Creating
Documentation (cont)
1.
Decide on a Name for the Documentation

Should reflect its contents and purpose E.G. 
POSMaster User’s Guide or AMPd Reference
Manual.
2.
Clearly Define the Purpose of the Documentation

Specifically define what it should achieve.

Focus on this definition throughout the
documentation creation process.

You might even decide to split the documentation
into two separate entities, E.G.  two manuals,
depending on their focus.
16
Steps for Creating
Documentation (cont)
Define Your Intended Audience
3.


Gather the Necessary Information
4.





17
Understand the users, their needs and their mindset before
writing the documentation.
Throughout the documentation creation process, be sure to
question whether the documentation communicates effectively to
this audience.
Make sure you understand the system you intend documenting.
This may entail gathering information about the system, learning
how to use the system and interviewing developers and users.
You need to ensure that you have all the necessary information
that will be required to write the documentation.
Validate everything you are told.
E.G.  you or another developer may think that a task is done in
a certain manner, but are you certain that it is?
Steps for Creating
Documentation (cont)
5.
Design the Documentation


6.
Design the Table of Contents

Serves as a skeleton for the documentation so spend




18
Decide on an appropriate and usable design.
E.G.  determine the page size and layout to be used,
the fonts and colours to be used, etc.
time designing it well.
Do not start writing documentation until the design is
complete and you are satisfied with it.
Get the design reviewed or approved by others.
Involve the users as they may have valuable ideas and
opinions to offer.
Users may embrace the manual when it is complete
because they had a part to play in its creation.
Steps for Creating
Documentation (cont)
Write the Documentation
7.







19
Using the skeleton of the documentation already devised, write
the documentation from beginning to end.
If necessary, skip over “problem” topics and return to them later.
Writing the documentation should be an iterative process of
writing, reviewing, adding and amending content repeatedly until
you are satisfied that it will meet the needs of the readers.
This requires time and patience.
Don’t be concerned with editing the text at this stage.
The focus should be on the writing accurate content, not on
sentence structure and punctuation.
Throughout the writing process be sure to keep the intended
audience and the “big picture” in mind – you are creating
documentation for a specific purpose for a specific audience and
which needs to satisfactorily meet their needs.
Steps for Creating
Documentation (cont)
Edit the Documentation
8.
To improve readability, accuracy, etc…
Requires much time and patience.


Proofread the Documentation
9.
Once you have edited the documentation and are satisfied with the result,
you should hand it over to a proof-reader to proofread.
The proof-reader’s job is to ensure accuracy, completeness, consistency
and usability by:


•
•
•
•
•
•
Create the Index
10.

20
Marking factual errors
Marking spelling errors
Indicating missing information
Indicating errors of emphasis
Commenting on style and grammar
Commenting on layout and design
If appropriate for the form of documentation and its requirements, create a
detailed index as an additional mechanism for guiding the reader to
desired content.
Steps for Creating
Documentation (cont)
Produce the Documentation
11.




Maintain the Documentation
12.




21
Investigate your options and make use of persons with professional skills.
Attention must be given to the quality of the printing, the binding and the
presentation of the documentation.
Specific attention must be given to the usability of the final documentation.
E.G.  a perfect-bound manual (where the pages are glued down the
spine so that the manual looks like a novel) looks nice, but will it stay open
on the desk while the user tries to read from it and type at the keyboard?
To be effective, the documentation must be kept up to date.
Plan for the maintenance and revision of the documentation.
E.G.  for a user manual ask yourself how easy it will be to replace a
page or set of pages if some aspect of the system changes.
Maybe the entire manual will be replaced in this event, or maybe the
documentation can be designed to allow selected sections or pages to be
updated and distributed, remembering that the table of contents, indexes,
etc will need to be updated and redistributed too.
Designing the
Documentation




22
First impressions last  strive to create professional,
attractive, usable, and effective designs.
If the documentation is difficult to use or understand,
users are likely to reject it.
Keep the user in mind at all times – the design must be
appropriate for the intended audience.
Consider how users will use the documentation, as
well as the environment in which they will use it, and
design accordingly.
Designing the
Documentation (cont)

Page Size and Thickness


23
Choose a suitable page size according to
what will be most appropriate and usable for
the reader.
Paper type and thickness is also important
 too thin the text on the reverse side may
show through, too thick, the pages may be
too stiff and may make the documentation
unnecessarily thick.
Designing the
Documentation (cont)

Page Layout

Select suitable styles for common elements:
•
•
•
•
•
•
•
•
•
24
Headings: Always ensure that headings at different levels can be easily
differentiated E.G.  use a different font size for each heading level
A page header and footer: Should it be placed on each page?
Page numbers: Format and placement
Body text: Typography – discussed later
Captions: Titles used to describe or explain illustrations, screenshots, or tables.
Lists: E.G.  If bullets will be used, what bullet symbol will be most appropriate?
Will numbers be used? How will numbered lists be formatted?
Tables: Give each table a suitable, descriptive caption.
Notes and warnings: Should have a different appearance to the main body text.
Warnings must get the reader’s attention and must have a strong visual impact.
Table of contents and index: The contents page does not have to list every
heading in the documentation. If the list of the full hierarchy of headings is lengthy,
rather list only the top two or three levels of headings and provide a detailed table of
contents for each chapter or major section.
Designing the
Documentation (cont)

Page Layout (cont)

Use suitable margins:
•
•

Use lists:
•
•
•

Page layouts are best when they are kept simple.
Use standard designs:
•
•
•
•
•
•
25
Use lists as often as possible for ease of reading.
For a list of steps, try to keep the steps to eight or less.
If the list contains more than eight steps, break the list into subsets of eight or less steps, with a
couple of sentences between each group to explain where the reader is in relation to the sequence
steps he or she is following (Crown, 1992).
Keep it simple:
•

Top, bottom, and side margins  if too small, pages will look too busy.
Multiple columns  be sure that there is sufficient space between each column.
Use standard designs that the user might already be familiar with.
Maintain a consistent design throughout the documentation and also across multiple related items of
documentation.
E.G.  the design used for each manual in a set of manuals for an application should be standard
across all the manuals.
Standardization causes familiarization.
When users become familiar with the way information is presented on one page or in one manual,
they are more easily able to understand and find information on other related pages or manuals.
Crown (1992) cautions against trying to force material to adhere to a standard layout if it is not
appropriate for that material.
Designing the
Documentation (cont)

Page Layout (cont)


Reuse previous designs
Strive for maximum usability:
•
•
•
•

Maintain your focus on the needs of the user – not your needs.
Be sure he or she will be able to find information quickly and easily.
Cater for users of different skills levels.
E.G.  split up a manual into parts: Part 1 for the beginner’s guide, Part
2 for the actual manual, and Part 3 for technical detail or information for
experienced users
Ensure that the design is non-distracting:
• The information that the documentation holds should attract the user’s
attention; the design of the documentation, or lack thereof, should not.
• Minimize busyness E.G.  lots of information, colours, shades or lines.


Call upon expertise if necessary
Test the design:
• Before accepting a design, test samples of the various styles and then
select the best one, possibly refining the design even further.
• For printed documentation, this may entail printing out sample styles.
For online documentation, it may entail producing online samples.
26
Designing the
Documentation (cont)

Graphics, Illustrations and Tables

Try to include screen shots, sample reports, graphics,
illustrations, diagrams, tables, icons and clipart graphics to
spruce up the content, bearing these guidelines in mind:
• They must serve a real purpose
• Make sure they make sense
• Make sure they are conveniently located
• Make sure they are consistent
• Never overdo it
• Seek expertise if necessary
27
Designing the
Documentation (cont)

Typography

Typography is concerned with the style and appearance of printed matter.
This includes the size and style of fonts. The following guidelines are useful:

Choose appropriate fonts: Text must be easily legible. Fancy fonts must be
avoided, especially for body text.
•
•
•
•
28
Serif fonts  Times or Garamond, for body text.
A different font may be used for main section headings or chapter headings, and for
messages that require the user’s attention. Fonts like Avante Gorde etc …
When the documentation features text that an application displays on the screen
E.G.  to illustrate textual output, use the same font as that used by the software to
display the text. Often, Courier is used for this purpose.
Do not use too many fonts as this can cause visual clutter.

Use fonts consistently

Use italics and boldface sparingly

Use appropriate font sizes
Designing the
Documentation (cont)

Typography (cont)





29
Do not use all uppercase text
Choose appropriate line spacing
Use an appropriate line length: Ideally not
less than 20 and not be more than 60
characters. Approximately 9 or 10 words per
line are best for ease of readability.
Use appropriate justification
Use colour sparingly
Designing the
Documentation (cont)

30
Numbering
 Decide on an appropriate list style: A numbered list
should only be used when there is a specific reason
to use numbers E.G.  to indicate order of
importance or multiple steps. Bullets should be used
in all other cases.
 Avoid numbering elements unnecessarily: Avoid
numbering headings, tables, figures, etc… unless
they are referred to from another point in the
documentation.
 Avoid complicated section numbers: Avoid
complicated section numbers, such as Section
6.2.1.2.
Designing the
Documentation (cont)

Documentation Structure

Decide on the overall structure of the documentation. E.G:
•
•
•
•
•
•
•
•
•
•
•


31
Title page
Copyright, disclaimers, trademarks
Warranty page (for external documentation)
License agreement (for external documentation)
Foreword
Contents page
Introduction
Main body chapters (or sections)
Appendices
Glossary
Index
The foreword might contain a brief introduction to the system, the purpose
and structure of the manual, a description of what information it contains,
where a user should begin based on his or her skill level, and how the user
should use the manual.
Include a glossary to explain difficult terms and concepts.
Designing the
Documentation (cont)

32
Documentation Structure (cont)
 Decide whether you will have chapters, sections,
or both
 Consider including chapter/section summaries
 Consider explaining the conventions and styles
used. The special symbols, typestyles, and other
devices you might use in the manual should be
explained near the front of the documentation. E.G. 
you should indicate what notes and warnings look
like, and how key combinations (CTRL+S and ALT+X
etc…) are shown.
Designing the
Documentation (cont)

Documentation Structure (cont)

Consider using chapter/section dividers:
• Tabs
• Solid block markers: A solid black (or coloured)
block tab can be printed on the outside of the
page so that when the manual is viewed from the
side the black mark on the edge of each page
becomes a black (or coloured) marker marking the
depth of the number of pages in the section.
• Varied page colours
33
Designing the
Documentation (cont)

Documentation Structure (cont)
 If you choose to use dividers such as these described
above, be sure to follow these guidelines:
• Be consistent: Use the dividers for all sections at the
same level in the hierarchy. E.G.  do not use a divider
for one chapter or level one section and not another.
• Ensure the documentation is thick enough: The
documentation should have enough pages to make the
dividers worthwhile, preferably more than 80 pages;
otherwise they will look silly (Crown, 1992).
34
Designing the
Documentation (cont)

Main Body Structure
 When designing the table of contents for the
documentation:
• Avoid lengthy topics: Avoid having lengthy topics that
seem to continue endlessly over many pages. Try to
make lengthy topics more manageable by subdividing
them into subtopics
• Ensure that information will be found easily: Ensure
that the content is structured in such a way that the
reader will be able to find the information he or she
might look for
• Group topics logically: Ensure that topics are grouped
in a logical order that will make sense to the reader
35
Writing the Documentation

Make it user-friendly:





Make it easy to understand:

36
Usability is crucial.
In the same way that a system’s user interface is tailored to
its users, effective documentation is easy to use and is
tailored to its readers.
Always keep the users in mind and evaluate the
documentation from the user’s perspective.
Determine what they know, what they need to know, and
whether the documentation will give them what they want
and will answer the questions they may have.
This may entail using language that will be easily
understood by the reader and using graphics, diagrams,
graphs, etc to convey information in a more meaningful way.
Writing the Documentation
(cont)

Specific guidelines:

37
Be clear: Express the content in ordinary language and short sentences,
remembering that the reader must always be able to understand what you
are writing. To write clearly, follow these rules:
•
Use simple, familiar words. Avoid jargon and technical terms. If you have to use
them, make sure that they are clearly defined. If the user does not need to know
about a jargon word, do not use it.
•
Avoid using abbreviations unless you know that the reader will be familiar with them.
If you use them, always include the full word or phrase the first time it appears and
include the abbreviation in parentheses. Avoid using abbreviations in headings.
•
If you use an acronym that is not well known, define it. Spell out the acronym the
first time it appears and include the acronym in parentheses. If the acronym is used
in a heading, spell it out in the first sentence after the heading, if it has not been
spelled out previously.
•
Use simple sentences and paragraphs. Avoid long sentences (more than 30 words)
and long paragraphs. Each sentence and paragraph must convey a single idea.
Unrelated information must not be mixed in the same sentence or paragraph.
Ensure that each paragraph has a main point.
•
Use diagrams to help explain difficult concepts.
Writing the Documentation
(cont)

Specific guidelines (cont):
 Be concise: Write what needs to be said in the
fewest number of words, but without sacrificing clarity.
Ensure that main points are stated directly, possibly
by making use of numbered or bulleted lists:
• Replace phrases with single words.
• Reduce words to a minimum.
• Eliminate text that is irrelevant to the point you are
making.
• Remove all repetition.
• Avoid tautology (unnecessary repetition of words). E.G.
 instead of “merge together” use “merge”, and instead
of “absolutely essential” use “essential”.
38
Writing the Documentation
(cont)

Specific guidelines (cont):

39
Be concrete: Be specific and express and illustrate the content fully to ensure that
readers completely understand it. Avoid vague terms and generalizations:
•
When possible and appropriate, keep to provable facts and figures. E.G.  in a user manual, instead
of writing “This software generates monthly statements quickly” write, “This software is able to
generate 5,000 statements in ten minutes.”
•
Use strong action verbs.
•
Write in active voice as it brings interest and a sense of activity to the writing. E.G.  instead of “The
setup program should be loaded” write, “Load the setup program”. Writing in active voice also
requires fewer words, but can often tell the reader more. Using active verbs makes your sentences
more specific, personal, concise and emphatic.
•
Use present tense. Present tense is preferred for instructional text and to describe information, past
tense is used to report results or to provide historical anecdotes, and future tense is used to describe
what will or might happen.
•
Use actual examples of key features to take the user step-by-step through the process of invoking a
function, using it, and then turning it off or moving to something else. Users find it much easier to
follow examples and modify them to suite their own circumstances than to figure out what to do from
a generalized description.
Writing the Documentation
(cont)

Specific guidelines (cont):
 Be coherent: Organize parts well and ensure that
content flows logically.
• Sentences must flow logically.
• Always divide the content into logical, clearly labelled
sections to assist the reader in finding information
quickly.
• Be consistent with terminology, abbreviations and
overall design elements, such as colours and
formatting.
• Provide references to related supporting information.
40
Writing the Documentation
(cont)

Specific guidelines (cont):

Be conversational: Write as you would speak to your
readers:
• Where appropriate, personalize your writing. Get the user
involved by referring to him or her. Try to use “you” and “we”.
E.G.  “We recommend that a backup be made after each
work session” is better than “ It is recommended that a backup
be made after each work session” . Similarly, “Look at your list
of customers” is also more personal. There are times though
that it is best to avoid using “you”, such as: where the user
made a mistake E.G.  “you failed to …”, in documentation
where informal writing is inappropriate, and when the
documentation will be used by different groups of users.
• In informal documentation (such as user manuals), you may
make use of contractions, such as “you’ll” instead of “you will”
and “don’t” instead of “do not”.
41
Writing the Documentation
(cont)

42
Specific guidelines (cont):

Provide users with features and benefits: Explain the
benefit that results from a feature or action. Users want to
know what something does and how it will help them do
their work. E.G.  instead of writing “This word processor
has a built-in thesaurus” write, “This word processor has a
built-in thesaurus. This means that a single keystroke will
bring up a list of words that can be substituted for the
highlighted word. This will help you write more effectively.”

Keep your writing positive: Avoid negative terms like “no”,
“won’t”, “cannot”, “never”, and “impossible”, except in
warnings. E.G.  instead of “ It is impossible to offer
customer support for JumpMaster if you do not sign and
send us the attached warranty card…” write, “As soon as
your signed warranty card reaches us, we will be able to
offer customer support for JumpMaster…”
Writing the Documentation
(cont)

Specific guidelines (cont):

Choose words that build images:
• Using comparisons: Compare something to what the user is
already familiar with (E.G  when illustrating the capacity of a
CD you could say that it can hold all the information contained
in a typical thirty-volume set of encyclopaedias).
• Using specific examples: Readers benefit from examples,
such as screenshots in user manuals, or example
walkthroughs of procedures.
• Using concrete nouns: Use nouns that represent something
that the user can see, touch, smell, feel or taste. E.G. 
instead of the word “ thing”, use a word that is more specific.
43
Editing the Documentation

44
Editing the documentation is the task of improving its readability, clarity, accuracy, etc…
The documentation must be carefully examined, page-by-page, to identify errors or
problems. No formal documentation is complete unless it has undergone the editing
process:

Be critical: Question everything. Determine all areas where improvements can be made.

Assume the role of the reader: Put yourself in the reader’s place and evaluate how he or
she will experience the documentation.

Evaluate according to purpose: Check that the documentation meets the purpose you
originally defined for it.

Evaluate according to user needs; Check that the documentation will meet the needs of
its specific users.

Evaluate the quantity and quality: Check for correct quantity and quality of the content.

Ensure accuracy: Evaluate the documentation for technical accuracy.

Look for missing content: Look for areas where necessary information is missing.
Editing the Documentation
(cont)

Some guidelines (cont):

Ensure consistency:
•
•
•
•
•

Check the language: Check grammar, spelling, punctuation, and language form and
structure.

Check all cross-references: Look for cross-referencing mistakes and omissions.

Consider first impressions: Ensure that the documentation is professional and that it is
attractive and aesthetically pleasing to its readers. E.G:
•
•
•
•
•
•
45
All manuals must look and read like they belong together and like one person wrote them.
Ensure style, look, structure, etc is similar across manuals.
Look for hierarchical heading inconsistencies.
Look for factual mistakes and inconsistencies.
Look for jargon inconsistencies.
Are the tabbings and margins consistent?
Are the page breaks appropriate?
Where possible, do new topics start on a new page?
Does it look professional when printed (if it will be printed)?
Will it look professional when bound (if it will be bound)?
Will it be usable when bound (if it will be bound)?
Creating the Index

Only create an index for your documentation once the documentation is complete (once edited and
proofread). The index is useful for showing what is not in the documentation and for listing the
terminology used in it. When creating the index it is important to construct it according to how the reader
will look up information:


Read through the documentation and underline the words (or word combinations) that you want in
the index. Use the underlined words to create the index.
Subdivide entries where appropriate:
Salary
Setting up
Amending
Viewing
Use the singular, rather than the plural, for the subheading.

Use “see” to direct the user to a more appropriate entry in the index, and “see also” to direct him or her to
a related topic.

Consider boldfacing significant references, but remember to make it clear what boldface references
mean.

Consider including additional indexes that the user may find useful, such as indexes for tables, reports
and figures.
46
Online Documentation

47
Nielson (2000) offers some general guidelines for creating online documentation:

Provide a means for the user to find what he or she is looking for: People turn
to documentation only when they are faced with a difficulty. Therefore, it is
essential that online documentation is searchable.

Instructions should be task-oriented: Instructions should emphasize how to do
things step-by-step. Background information should be limited because users
generally skip over it anyway.

Use conceptual models: Because background information might be limited it is a
good idea to provide a short conceptual model of the system (possibly by using a
diagram) to explain how the different parts of the system work together.

Explain difficult terms and concepts: Make use of hypertext links to link to
descriptions of difficult concepts or system-oriented terms.

Be brief: Online documentation should be brief.
Publishing Project
Documents Online






48
Consider publishing all the documentation pertaining to
a project to an internal Web site for easy access by all
participants.
This is useful for requirements documents that are
used by a diverse audience.
The hypertext format can allow readers to view the
information to the level of detail they desire.
E.G.  project sponsors can view information at a
high-level to ensure that all business objects are met.
Programmers can use links to “drill down” to increasing
levels of detail.
Any other useful information can also be included on
the Web site, such as results of nightly builds, results
of regression tests and performance statistics.
Publishing Project
Documents Online (cont)

49
When publishing project documents online, keep the following in mind:

The documents must be kept up to date

Publish automatically: The Web content should be generated automatically
from the information in the repository and published without human
intervention. If you have to maintain the Web content manually then the
“avoid duplication” principle has been violated.

Date stamp each document: Always include a date stamp and a version
number on each document. This will make it easy for the reader to determine
what is up to date and what has changed.

Separate content from presentation: Orthogonality also applies to
documentation. There should be decoupling of content and presentation.
Truly orthogonal documentation will allow you to change the appearance
dramatically without changing the content, E.G.  by using style sheets. This
will enable you to present the same documentation in different formats, for
example, as Web pages or online help.
Further Principles and
Practices

There are a number of more general documentation creation
guidelines that should be kept in mind:

Use document models:
• Copy the format and outlines of manuals and tutorial materials deemed
to be “excellent” by readers. These are good models to build upon.

Avoid duplication:
• E.G.  including meaningful comments in code and using a tool to
automatically generate documentation from the code and these
comments reduces the time and effort required to keep the
documentation up to date – maintaining one set of knowledge is better
than maintaining two.
• This concept can be applied to other aspects of a project. E.G.  the
possibility of using a specification document and exporting the
information it contains into different views, such as a database schema,
a high-level language record, etc…
• Changes are made in only one place (the specification document),
thereby eliminating redundancy and allowing changes to be made more
easily.
50
Publishing Project
Documents Online (cont)

General documentation creation guidelines (cont):

Indicate the date and version of the documentation:
• Always be sure to provide a date and a version number of
every item of documentation, from project documentation to
user documentation, from a one-page document to a thick
manual.
• Ensure that this information can be easily found by anyone
who looks for it. These will help readers to determine when the
documentation was modified and to distinguish the
documentation from older versions.

Create a style guide:
• If a set of documentation items is being created, or if multiple
documentation writers are involved in the documentation
process, a style guide can contribute to the success of the
documentation.
51
Further Principles and
Practices (cont)

General documentation creation guidelines (cont):

Create a style guide (cont):
•
A style guide provides guidelines for the usage of styles within documentation. It
might provide guidelines for the use of:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
52
Terminology – to ensure consistent use of terms and jargon
Spelling – of difficult words and words having multiple spellings
Company and product names
Problem words
Abbreviations - first mention and subsequent mentions
Acronyms - first mention and subsequent mentions
Quotation marks – single or double
Italics
Numbers and symbols
Punctuation
Lists – punctuation, capitalization, etc
Headings
Captions, figures, and tables
Typefaces for screen representation and screen messages
Key descriptions (E.G.  Ctrl-Z, CTRL-Z or CTRL+Z).
Warnings
Header and footer styles
Styles for a list of steps (for example, bullets or numbers). Once established, the style guide
should be adhered to unless there is good reason to deviate from it.
Further Principles and
Practices (cont)

General documentation creation guidelines (cont):

Use professional writers and editors:
• Particularly for large projects, consider using professional writers,
editors and graphics personnel to produce the user manuals and tutorial
materials.
• They create clearer and more effective manuals and tutorials than
untrained personnel.

Test the documentation:
• Test all documentation concurrently with software testing.
• Drafts of the major user manuals and the online help text will therefore
have to be available during software testing.
• Usability lab tests can also be conducted whereby customer volunteers
attempt to exercise applications for normal business, using only the
application and its manuals and tutorial materials.
• Specialists monitor their success or failure.
• Internal documents can also be studied in a similar fashion.
53
Further Principles and
Practices (cont)

General documentation creation guidelines (cont):
 Introduce users to user documentation:
• To increase the success of user documentation, it can
be introduced to users by means of a short training
program to prove the worth of the documentation. This
can:
• Build enthusiasm for the forthcoming release of the
documentation.
• Establish user ownership of the documentation.
• Establish user pride in the documentation.
• Build user confidence in the documentation.
• Familiarize users with the design, layout, conventions,
and style.
54
Further Principles and
Practices (cont)

General documentation creation guidelines (cont):
 Introduce users to user documentation (cont):
• In this way, users will be more inclined to use the
documentation as a self-training aid to help themselves,
thus reducing the amount of training required.
• Furthermore, users will gain more confidence in the
documentation and the system, and will be more
inclined to use the system to its full potential.

Encourage reader suggestions:
• Supply reader comment forms for correcting errors and
pointing out problems as part of every published
document.
• Allow for online comments to be sent via the Internet.
55
Conclusion

Special attention must be given to the creation of documentation for a
software system, as it is one of the most important parts of such a system.

The primary goal of any documentation writer should be to create effective
documentation, whether it is internal project documentation or some form of
user documentation.

Writers of documentation must ask themselves whether their documentation
will not only be usable by its intended audience, but actually used,
remembering that all documentation must be specifically geared towards its
intended audience.

Writers of and contributors to internal project documentation must be
conversant with one more fundamental rule: internal project documentation
is not an end-stage process of programming. It should be carried out during
all the previous programming steps, as it is an integral part of the overall
development process.
56