Step By Step - Practices

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:

1. That provides enough fodder for you, the writer, to start planningthe structure of the manual.
2. 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.
3. The project schedule will typically never allow time betweendevelopment and delivery for anything more than very superficialdocumentation.
4. 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:

1. Planning
2. Stylesheet creation
3. Development
4. Review
5. Version management
6. Delivery

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.

>>> More Practices Articles          >>> More By Deepa L, (c) Melonfire

blog comments powered by Disqus