Home arrow Practices arrow Page 2 - Writing A User Manual (part 1)

Step By Step - Practices

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.

  1. Writing A User Manual (part 1)
  2. Step By Step
  3. Asking The Hard Questions
  4. Making Friends And Influencing People
  5. Being Conventional
By: Deepa L, (c) Melonfire
Rating: starstarstarstarstar / 40
December 27, 2002

print this article


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
escort Bursa Bursa escort Antalya eskort


- Calculating Development Project Costs
- More Techniques for Finding Things
- Finding Things
- Finishing the System`s Outlines
- The System in So Many Words
- Basic Data Types and Calculations
- What`s the Address? Pointers
- Design with ArgoUML
- Pragmatic Guidelines: Diagrams That Work
- Five-Step UML: OOAD for Short Attention Span...
- Five-Step UML: OOAD for Short Attention Span...
- Introducing UML: Object-Oriented Analysis an...
- Class and Object Diagrams
- Class Relationships
- Classes

Developer Shed Affiliates


Dev Shed Tutorial Topics: