Writing Good Software Documentation
|
|
|
| 5.0/5.0 (1 votes total) |
|
|
|
Adriana Iordan November 30, 2006
|
Adriana Iordan |
Adriana Iordan is a Web Marketing Specialist at Avangate B.V. She has
in depth knowledge of internet marketing services and website analysis
applied to the software industry and e-commerce development. Avangate
is an eCommerce platform for electronic software distribution
incorporating an easy to use and secure online payment system plus
additional marketing and sales tools. |
Adriana Iordan
has written 1 articles for CGIDir. |
View all articles by Adriana Iordan... |
Writing
software documentation may seem extremely easy for some of us, whereas
others may consider it one of the most difficult tasks they could ever
be asked to do. The generic term for this kind of writing is
"technical writing". A person who does this job is generally referred
to as a "technical writer", with quite extensive knowledge of software
and technology and with a deeper understanding of the logic behind the
software, or a "technical writer", a person who, although somewhat
overwhelmed by all the denominations and the algorithms of the
software, is accurate in producing a proper technical text. Nevertheless,
regardless of the orientation of the writers, be them more technical
than writers, there are some things that need to be considered before,
during and after the writing process. - Before Writing
- Know the Software
- Training
Make
sure you receive proper training for the software that you are about to
document and that you have the software explained to you, step by step. - Experiment
Have
the software installed on your machine; make sure you also have access
to as musch as possible of the necessary software related information,
and that you have access to all the functionalities of the software.
Explore all its functions, and don't be afraid to ask the engineers
whenever you are not certain about the influence of, let's say, an
unchecked checkbox or radio button on the process thatyou are
documenting. Don't assume anything, you could be wrong. - Gather information
This
may mean older documents, definition documents for certain
functionalities or specifications, general PowerPoint presentations,
marketing documents, etc. They may help you along the way.
- Identify the Target Audience
This
is of utmost importance. You have to know beforehand to what kind of
public the document you are about to produce addresses to, so that you
know how to adjust and adapt the style and the informational content of
the document. Again, ask the engineers, the product managers, about the
audience. You don't want to be too technical for a non-technical
audience, or vice versa.
- During the Writing Process
- Keep It Simple
- Avoid creating a lot of styles. Too many styles can make a document hard to follow.
- Do
not include header and footer in the first two pages of the document
(the ones containing the name of the company that produces the
application, the name of the document, date of creation, copyright
issues, support department contact information, and document version
history). Start using header and footer from the Table of Contents
section.
- Refrain from inserting symbols (such as exploding bombs or the like) for error messages or notes.
- Use
only black for text. You can highlight terms or names of buttons,
menus, windows, tables, etc. by using bold letters or italics.
- Be Accurate
With Text
- Respect
all the documentation requests, coming either from the client or from
your direct supervisor, pertaining to the contents and layout of the
document.
- Always check the spelling and grammar
- Avoid
ambiguous or empty phrases. Do not describe a checkbox by simply saying
"Select here to do this." Explain the effect of checking or not that
respective checkbox on the process that you are documenting and on the
behavior of the software as a whole. Avoid describing fields by using a
simple, for example, "Enter the file name", or "Enter user ID /
password". You must provide more information, such as the location
where files can be found or saved, the length and composition of user
IDs and passwords, in what way the details provided by you in these
fields will influence the evolution of the process you are documenting
and the behavior of the entire software, etc.
- Describe with
accuracy text fields, checkboxes, radio buttons, spin boxes, drop-down
lists, etc. Do not assume that the readers will know what they are or
what they should contain.
- Make sure that the names of user manuals or products that you refer to in your document are correct.
- Use a simple NOTE whenever some particular aspect needs to be brought to the reader's attention.
- Do
not insult your reader's intelligence by pointing out the really
obvious. For example, it suffices to state only once how to start the
application. Any further reference to this inside the manual is not
necessary.
- Don't burden your readers with unnecessary,
irrelevant information. What you need to do is fulfill your readers'
need for information on a particular topic, not boast about your vast
knowledge.
- It is also preferable to express an idea in a simple way than risk an intricate, complex formulation.
- Always
be careful with gender-neutral writing. Prefer using the imperative
mood (Do this..), the second person pronoun (you) over the third person
plural pronoun "they" as singular pronoun (mainly because many of your
readers may not grasp its real meaning) or over the third person
singular pronoun "he" (you may sound gender-biased) or "the user".
Also, avoid such phrases as "he/she" or "he or she".
- When you
have tables in your document, make sure you select from Table
Properties the "Allow row to break across pages" option and, for the
top row of your table, the "Repeat as header row at the top of each
page" option. This way you will avoid those huge blank spaces created
when a table is too big to fit in a smaller part of the page and it is
automatically moved on the next page of the document.
With Pictures / Screen Shots / Diagrams
- Prefer using picture capture software over the simple, less accurate, (Alt+) Print Screen function of Windows OS.
- Use
the Windows Standard color scheme for images that need to be inserted
in your document, so that a later update will be easier (no need to
change all the pictures) and there will be no discrepancies between the
images inserted in that document by (possibly) different persons.
- Have
as many fields as possible filled in the screen shots that you take, so
that your readers receive enough relevant information.
- You do
not necessarily have to add images of the buttons that contain only
text (e.g. OK, Cancel, Apply, Advanced, etc.). Just the button's name
written with bold letters should suffice. Nevertheless, you should
illustrate the image-buttons.
- Do not insert the images directly from the picture capture software. Save them in a separate folder for further use.
- Use
diagrams when you want to illustrate the work-flow of the application
or of one part of the application that you are documenting. Also, you
can use diagrams to illustrate the structure or hierarchy of the
different functionalities of the software.
- Insert pictures
after each step described in your document, and for each action that
needs to be taken to obtain a specific result. It will be easier for
your readers to follow the step-by-step approach.
- Place a caption under each of the inserted pictures, so that the readers know what they are looking at.
- After Finishing Your Document
- Proofreading
Go over the document once or twice, to make sure that the grammar you
used is accurate, that you have spelled the words right, that you
haven't skipped any important information and that you have formatted
all your text properly.
- Insert the Table of Contents Once
you're sure that your text is OK, insert the table of contents. It is
preferable that it has no more than 3 - 4 levels, but this depends on
what you deem important and how obvious you want some information to be
to your readers.
- Insert the Indexes It is now time to index the
most important terms and phrases in your document. Remember to update
the table of contents afterwards.
- Send the Document to be
Reviewed After checking that everything is in order, table of contents,
indexes and text altogether, send the document to one of the Subject
Matter Experts (SME) for review. Ask that they use the Track Changes
function, so that you can see exactly what they have modified and where
you should concentrate your attention. After you receive it back, you
either have to go over some of the above-mentioned steps in order to
correct possible errors of fill in some information gaps, or the
document will be approved and you can forward it to the proper
department so that it can be distributed to customers, and you can
start working on the next document.
Read full article. Copyright © 2006, www.avangate.com
all rights reserved. This article was written by a Web Marketing
Specialist at Avangate B.V. Avangate is an eCommerce platform for
electronic software distribution incorporating an easy to use and
secure online payment system plus additional marketing and sales tools.
|