Writing A User Manual (part 1) - Making Friends And Influencing People (
Page 4 of 5 )
Another important aspect of planning is figuring out your resource
requirements, especially if you are a technical writer expressly brought
in to the project for support documentation. There are a number of
resources you can tap - here's a brief list:
1. SMEs: SMEs (Subject Matter Experts) are your guides throughout the
documentation project. These are usually members of the development team
who will familiarize you with the application, answer your questions and
generally be your information bank. This is a good time to determine
which developers from the team are to be your SMEs.
Your relationship with the SMEs will go a long way in determining the
success of this task.
- Determine a method of communication that is suitable to both. An
option is that you post your questions to the SMEs via e-mail, who may
then 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 your
question lies a lot of information, and what you get to know will be in
direct response to only what you ask. So, spend some time getting your
questions 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 the
project; any change in the software that affects flow, functionality or
interface affects your document. In fact, even with changes that don't
affect the user interface, it's a good idea to be in the loop, because
there could be reactions that you would want to know about. Again, try
and set up an information chain or e-mail trigger for the same.
2. Project specifications: Needless to say, getting acquainted with the
specification documentation is crucial to understanding the project. The
objective of the project from the customer's business point of view is
usually defined very clearly in these - make sure you re-use that, as
your users will relate to it.
3. Prototype: Since you're going to be writing about the behavior of
each feature in the software, playing around with the actual interface
is a must. On the other hand, documentation usually begins in parallel
with development, so you don't really have anything to go by.
The workaround here is the prototype. The delivery of the prototype by
the development team will be a big milestone in your schedule...because
that's where you actually start developing the manual. Get this date
from the developers, and circle it in your calendar.
Note also that changes take place frequently in the early stages of
development, not only in the behavior of the software, but also in the
interface elements, text labels and messages. Ensure that your manual
reflects the delivered product by referring to the latest prototype.
4. Schedule: The cornerstone of this planning stage is the schedule. An
important consideration here is the dependencies between your tasks and
other milestones in the schedule. Understand the developers' schedule
and build your own based on that. Your milestones could be something
like this:
- User profile generated
- Product information assimilated from specifications
- Stylesheet finalized
- Table of contents/outline complete
- Outline sent for review
- Outline returned with comments
- Comments incorporated and outline available for sign-off
- Sign-off
- First draft sent for review
- First draft returned with comments
- Comments incorporated and draft available for sign-off
- Sign-off
- Second draft sent for review
- Second draft returned with comments
- Comments incorporated and draft available for sign-off
- Sign-off
- Third draft sent for review
- Third draft returned with comments
- Comments incorporated and draft available for sign-off
- Sign-off
- Delivery
Review and revision efficiency (addressed in the second part of this
article) are crucial to ensuring that three drafts are all it takes.
