Writing A User Manual (part 1) - Step By Step (
Page 2 of 5 )
One of the first decisions project managers face is whether the user
manual should be a development team production, or whether a technical
writer should be assigned the job. Practically, this decision is a
function of the size and budget of the project, but an understanding of
a technical writer's contribution helps in making an informed choice.
While the developer's responsibility is to be an expert on the
structure, features and working of the software, the technical writer is
responsible for understanding the users' mindset - their expectations,
present level of expertise and possible questions - and then formulating
the best way to communicate with them. The quality (ability to
communicate) of the support documentation directly affects the level of
after-sales support required. Since technical writers are trained in the
black art of communication, it usually makes more sense to hire one for
the support documentation needed, rather than have a developer do it.
Documentation, as a process, begins (ideally!) right at the point where
the development team has finalized the software design, because:
- That provides enough fodder for you, the writer, to start planning
the structure of the manual.
- You have a better chance of understanding the software if you ask
questions (lots of them!) while it's still in development.
Post-development, the team is usually into the next project, and you end
up doing a lot of backtracking and guesswork.
- The project schedule will typically never allow time between
development and delivery for anything more than very superficial
documentation.
- Most important, the ideal scenario is to release the documentation in
time for the software testing, so that the test team tests the documents
as well as the software simultaneously.
An organized process of documentation will usually have the following
phases:
- Planning
- Stylesheet creation
- Development
- Review
- Version management
- Delivery
In this article, I'll be focusing on the first two steps, with a list of
things you should keep in mind when formulating the structure and style
of your manual.
