Need to write a user manual, but don't know where to start?Our handy two-part guide takes you through the process, explaining theimportance of proper planning in the early stages and demonstrating howto build a consistent and usable stylesheet for document formatting.
One of the first decisions project managers face is whether the usermanual should be a development team production, or whether a technicalwriter should be assigned the job. Practically, this decision is afunction of the size and budget of the project, but an understanding ofa technical writer's contribution helps in making an informed choice.
While the developer's responsibility is to be an expert on thestructure, features and working of the software, the technical writer isresponsible for understanding the users' mindset - their expectations,present level of expertise and possible questions - and then formulatingthe best way to communicate with them. The quality (ability tocommunicate) of the support documentation directly affects the level ofafter-sales support required. Since technical writers are trained in theblack art of communication, it usually makes more sense to hire one forthe support documentation needed, rather than have a developer do it.
Documentation, as a process, begins (ideally!) right at the point wherethe development team has finalized the software design, because:
That provides enough fodder for you, the writer, to start planningthe structure of the manual.
You have a better chance of understanding the software if you askquestions (lots of them!) while it's still in development.Post-development, the team is usually into the next project, and you endup doing a lot of backtracking and guesswork.
The project schedule will typically never allow time betweendevelopment and delivery for anything more than very superficialdocumentation.
Most important, the ideal scenario is to release the documentation intime for the software testing, so that the test team tests the documentsas well as the software simultaneously.
An organized process of documentation will usually have the followingphases:
In this article, I'll be focusing on the first two steps, with a list ofthings you should keep in mind when formulating the structure and styleof your manual.