Projects that deliver software systems or other systems
which require some degree of proficiency of the system's users must consider
developing that proficiency as a project deliverable. Depending on the
complexity of the system and the existing level of proficiency in the user
community the proficiency may have to be delivered by training or a good User
Manual or User Guide may be sufficient. The User Manual or User Guide delivered
with the system should not be treated any differently than the other components
of the system; quality standards should be established for the documents and
the team should ensure that the documents developed meet these standards.
There is another source of documentation for the project:
User Manuals or Guides that are part of system components purchased from a
vendor. The User Manuals or Guides are an important part of the product and
care should be taken in choosing a component with quality documentation.
Documentation is important to your project because it
explains how to use the system, or components of the system properly. In the
case of a purchased system component, the project team members directed to
integrate the component with the new system, or with using the software to
build the new system, will only perform their work proficiently if the
information they receive in User Manual is well written. Even when team members
can use the component without referring to the Manual, the Manual may contain
information that would allow them to perform their work more efficiently. To
derive this benefit from the Manual it must be well written. The user community
who will use the system your project is developing will experience a similar
benefit from documentation. They rely on these documents to tell them how to
use the system properly to do their jobs. The manual is an important part of
the education process even when users receive training. To do this job
properly, the documentation you develop must be well written.
Purchased Software or Components
Documentation should form a part of your decision making
criteria when selecting the best components or software to purchase. There are
many different approaches when selecting a vendor (if you are unfamiliar with
this activity, read up on your PMBOK® or review your PMP® Exam Preparation
training), but the one that I'm most comfortable with is the criteria matrix.
The criteria matrix simply lists all the criteria you will use to compare
products and vendors, the scores each of the product/vendor combinations get in
each criteria and the ranking of the criteria. The vendor who gets the highest
score usually gets the sale.
Include the documentation that accompanies the product in
the criteria you will use for ranking. Don't automatically rank documentation
at the low end of your priority scale. Documentation may be an important part
of the product, depending on its complexity, ease of use, and who will be using
it. The wider its use and the more complex it is, the more important the
documentation will be. There is no point in purchasing the best software or
component available if your team or user community can't use it!
Some other considerations when assigning a priority to
- Who will be using it? Are they sophisticated
users or novices?
- How widely will the component be used? Are there
only a handful of users (e.g. a project sub team) or will the component be used
- How mission critical is the component? If
failure to use the component properly would cause a catastrophic failure, the
priority should go up.
- How often will the component be used? How long
will it be used?
Answering these questions will
help you to prioritize the documentation realistically.
Scoring the documentation is a
more difficult question. You are probably the last person who should do the
scoring because you are highly unlikely to have to use the User Manual! The
people in your organization who will be using it, should be the ones to score
it. The first consideration is having a copy of the documentation available for
evaluation. Ensure that a copy accompanies any evaluation copies of the
software/component you receive for evaluation. The next consideration is the
quality of the documents. Are they clear? Unambiguous? Well organized? Are they
well written? Free of spelling and grammar errors? Is there an index? A
glossary? These are just some of the things to be considered when evaluating
It is a good idea to have actual
users evaluate both the component, or software, and the documentation. You
usually won't be able to get the entire user community involved in product
evaluations but try for a representative from each of the user groups. You may
have to settle for one representative from the user community. If that's the
case, make sure that evaluator is the least proficient, or most demanding
person available. You should do as much of the evaluation work as possible. For
example, your expert user community do not need to check the manual for
spelling, grammar, indices, etc., these things are well within your ability to
Schedule these evaluations and
assign people to perform the User Manual evaluation. Planning this activity
well in advance and communicating task assignments to the team will increase
your chances of having the work done.
Project Produced Documentation
Project produced documentation is the other side of the
equation. Just as we evaluate products we consider purchasing based on the
documentation that comes with them, so others will evaluate our products based
on the quality of our documentation. This logic applies even when your
customers are your own user community. A great system accompanied by poor
documentation will be perceived as a poor system by customers. Customers forced
to accept the poor product will be resentful and resist taking delivery.
How do you ensure that your documentation meets quality
standards? Establish those standards in much the same way you established them
for your product evaluation. Here are some criteria you may want to use as
- Is the document written clearly, concisely, and
in good English?
- Does the document address all the different uses
the system will be put to?
- Is the document free from spelling or grammar
- Does the document have an index (if it needs
one)? A table of contents? a table of figures? A glossary?
- Is the document easy to navigate? Can users find
the information they seek quickly and easily?
By now it will become apparent to any readers who belong to
the technical writers brotherhood that I am no expert in technical writing.
This brings me to my next point: hiring technical writers to write your User
Manuals or User Guides will serve 2 purposes, it frees up the BA or programmer
who otherwise might have been tasked with writing the manual and it ensures a
well written document. If the engagement of a technical writer as a contract
resource or full time employee is beyond your project's budget, make certain
that the person you do choose to do the writing is the most experienced
document writer available. People who are used to writing specifications that
others must interpret are one example.
Create your documentation from specifications the same way
your create your system. Specifications in this case don't have to do with
features or functions, rather they are directions on what should appear in the
document, how it should be organized, etc. For example, you may want to specify
that the document include a screen shot of any user facing screens as
illustrations. The specifications may be part of a Functional Specification or
Software System Specification, or it may be a stand-alone document. Normally,
documentation standards will be the same across all applications, features, and
functions and only the content will change. Document features that draw on
information across the entire document should be accounted for. Assign someone
on the team to compile the Table of Contents, Indices, Table of Figures,
Evaluating the written document against the established
criteria/specifications is the job of the Quality Assurance group, or the group
in your organization who perform this function. Testers should have to rely on
the User Manual to guide their exercise of the new system. If your
documentation won't be ready in time to QA test then ensure that it receives a
User Acceptance Test before implementation. Users performing this testing
should be given a copy of the User Manual to educate them on how to properly
exercise the system. This approach to testing has 2 benefits: it will make
testing more efficient and it will eliminate mistakes due to a lack of
proficiency with the new system.
Don't forget the support staff when evaluating purchased
software or components and don't forget them when planning your User Acceptance
Testing. It is vital that these folks become proficient with the system they
will be supporting. Don't treat your system's documentation as the "poor
relation" deliverable. Ensure that proper quality standards are
established and communicated, then verify that the documentation meets those
standards. Make certain that each user in the user community has a copy of the
User Manual when the new system is deployed. You can't force users to read the
manual but you can make it available and make them aware of it. Finally, don't
put the User Manual on a shelf and forget about it. The system you just
deployed will probably be around for some time, if it's a good system, and be
updated frequently. Make certain that the User Manual is updated
whenever there is a new release of the system which adds/deletes/changes
features or functions. The same quality standards should be applied to the
document updates as was used when the original document was written.