|
Writing Software Documentation
Thorough and well-written software documentation
can significantly minimize the volume of support
queries that a MicroISV receives. Take the time
to write clear documentation that will guide users
through the software.
Follow these tips to solid software documentation...
1. Native Speaker, Preferably A Technical
Writer
Technical writing can be arduous, and often requires
the use of complex terminology. It is imperative
that the individual writing the technical documentation
not only have a strong technical background, but
they must also have a very strong command of the
language that the documentation is being written
in. Use a native speaker to document the software.
2. Familiar With Software
The person writing the documentation needs to
be extremely knowledgeable about the software.
In order to properly document the software's functionality,
it is important that the writer have a complete
understanding of the software's features and functions,
and how they can be deployed to assist the customer
in accomplishing their tasks.
3. Use Technology
There is no need to reinvent the wheel in order
to generate a help file -- there are a number
of tools available that can be used to generate
a help file and build software documentation.
Use existing technology for documenting software.
Some popular and respected help file applications
include Help
& Manual, Help
Scribble , and Dr
Explain .
4. Make Documentation Visual
Include screenshots and graphical explanations
in the documentation, which provide visual images
corresponding to the documentation's text. The
images and graphics will often help customers
understand and follow along, especially when the
documentation deals with complex processes.
5. Proof, And Proof Again
The task of proofreading documentation is time-consuming,
and not always enjoyable... but it is, however,
a very necessary task. The individual responsible
for proofreading the documentation should not
be the same person who wrote it. If necessary,
use a third-party to review and proofread documentation.
6. Multiple Formats
The majority of documentation and help file tools
allow you to generate the output in a variety
of formats (html, pdf, web-based help, etc). Try
to provide technical documentation and help files
in a wide variety of formats, so the customers
can choose their own preferred format.
7. Make It Searchable
Make the documentation easy to search, so that
customers can quickly and easily drill down and
locate the information they are interested in,
or the details they need help with.
8. Keep It Simple
Keep in mind that some of the software users may
not speak the same language as you do, so try
to use simple terms to explain the software usage.
9. Consistency
Remain consistent throughout the documentation.
The formatting and terminology used in the documentation
should remain consistent throughout the entire
document.
10. Examples
Use examples to explain how the software's features
can be used to accomplish specific tasks. Nothing
illustrates a real-world solution like a real-world
problem.
11. Keep Up-To-Date
And finally, when writing documentation, be sure
to keep it up-to-date. Each time you release a
new software version, you should update the help
file and corresponding documentation.
Related Articles:
Tips
for Software Upgrades
How
to Launch and Announce an Application
How to Price
Software
Free
vs. Paid Software Upgrades
|
Developer
101
Software Documentation