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

Making Friends And Influencing People - 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


Another important aspect of planning is figuring out your resourcerequirements, especially if you are a technical writer expressly broughtin to the project for support documentation. There are a number ofresources you can tap - here's a brief list:

1. SMEs: SMEs (Subject Matter Experts) are your guides throughout thedocumentation project. These are usually members of the development teamwho will familiarize you with the application, answer your questions andgenerally be your information bank. This is a good time to determinewhich developers from the team are to be your SMEs.

Your relationship with the SMEs will go a long way in determining thesuccess of this task.
  • Determine a method of communication that is suitable to both. Anoption is that you post your questions to the SMEs via e-mail, who maythen respond in their spare time, or (if the explanation is long-drawn)schedule a meeting.
  • Ask the right questions. Understand that on the other side of yourquestion lies a lot of information, and what you get to know will be indirect response to only what you ask. So, spend some time getting yourquestions right.
  • Get familiar with the platform and terminology used in the software.This way, again, you make your meetings with the SMEs efficient.
  • Let the SMEs know that you need to know of every change made in theproject; any change in the software that affects flow, functionality orinterface affects your document. In fact, even with changes that don'taffect the user interface, it's a good idea to be in the loop, becausethere could be reactions that you would want to know about. Again, tryand set up an information chain or e-mail trigger for the same.
2. Project specifications: Needless to say, getting acquainted with thespecification documentation is crucial to understanding the project. Theobjective of the project from the customer's business point of view isusually defined very clearly in these - make sure you re-use that, asyour users will relate to it.

3. Prototype: Since you're going to be writing about the behavior ofeach feature in the software, playing around with the actual interfaceis a must. On the other hand, documentation usually begins in parallelwith development, so you don't really have anything to go by.

The workaround here is the prototype. The delivery of the prototype bythe development team will be a big milestone in your schedule...becausethat's where you actually start developing the manual. Get this datefrom the developers, and circle it in your calendar.

Note also that changes take place frequently in the early stages ofdevelopment, not only in the behavior of the software, but also in theinterface elements, text labels and messages. Ensure that your manualreflects the delivered product by referring to the latest prototype.

4. Schedule: The cornerstone of this planning stage is the schedule. Animportant consideration here is the dependencies between your tasks andother milestones in the schedule. Understand the developers' scheduleand build your own based on that. Your milestones could be somethinglike this:
  1. User profile generated
  2. Product information assimilated from specifications
  3. Stylesheet finalized
  4. Table of contents/outline complete
  5. Outline sent for review
  6. Outline returned with comments
  7. Comments incorporated and outline available for sign-off
  8. Sign-off
  9. First draft sent for review
  10. First draft returned with comments
  11. Comments incorporated and draft available for sign-off
  12. Sign-off
  13. Second draft sent for review
  14. Second draft returned with comments
  15. Comments incorporated and draft available for sign-off
  16. Sign-off
  17. Third draft sent for review
  18. Third draft returned with comments
  19. Comments incorporated and draft available for sign-off
  20. Sign-off
  21. Delivery
Review and revision efficiency (addressed in the second part of thisarticle) are crucial to ensuring that three drafts are all it takes.

>>> 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: