Writing A User Manual (part 1) (
Page 1 of 5 )
Need to write a user manual, but don't know where to start?
Our handy two-part guide takes you through the process, explaining the
importance of proper planning in the early stages and demonstrating how
to build a consistent and usable stylesheet for document formatting.
Depending on who you speak to, documentation is either the best part of
a software project...or the worst.
Most developers wouldn't be caught dead writing a user manual - they
much prefer spending their time building better, more efficient
algorithms. Their users, on the other hand, don't really care about the
code that powers a software application; they're more interested in
getting their work done quickly, with minimal errors.
That's where support documentation, in the form of a user manual, comes
in. Usually considered one of the least important deliverables, it is
slowly coming of age, as software companies begin to realize the value
of high-quality documentation that answers most user questions and
reduces after-sales support calls (and expense).
Support documentation allows the user to use the delivered software with
ease and efficiency. Ideally, it comprises:
- Interface text: The labels on interface elements like menu items,
fields, instructions, confirmations, error messages et al.
- Application messages: Operational error messages and warnings.
- Online documentation: Online help, tutorial and searchable help
pages.
- Print documentation: User manual and technical reference manual.
These, in totem, are the user's support system for usage of the
software.
This article focuses on the user manual, explaining, from a technical
writer's perspective, the process by which such a manual is developed,
reviewed and delivered. I believe, though, that the process and planning
tips are generic enough to apply to the other print documents, in
accordance with both their purpose and scope.
