Are you maintaining your documentation correctly?
As I've said in many PVT eZines, you
must write stuff down.
The other day, an interviewer asked,
"How many pages you written?"
"Somewhere around 30,000 pages delivered,
not including thousands of draft pages."
"You must love writing!"
"I don't love writing per se. I love
the applications. I love the results. In writing, you can create, let's say, the first level of reality.
By writing, you can begin to give intangible ideas form in the physical
"Can you imagine how many people discovered
the secret of fire and didn't write it down? The
news had to spread by 'tribal knowledge!'
"How many times did the secret vanish because some fire-novice asphyxiated himself and family? How many times
do think some do-gooder banned fire due to its dangers?
"It probably took eons to discover that
secret of fire - over and over! Eventually, I suppose, someone wrote the secret on a
cave wall or cocktail napkin..."
"Planning to write is not writing. Outlining...
researching... talking to people about what you're doing, none of that
is writing. Writing is writing." -- E.L. Doctorow
What is the documentation life cycle?
Anyway, when you write stuff down, you'll
eventually need to update it. (I'll talk here about large, important documents - Operations Manuals,
Technical Manuals, User Manuals, or maybe the secret of fire and how to
"Mike, what have you learned over
the years about maintaining documentation?"
Well, large documentation projects have
their own "life cycle." This cycle extends from conception to obsolescence. When you develop
large-scale documents, you'll typically iterate through the following:
- 1. Requirements.
- Includes definition, statement of goals,
preliminary analysis, functional specifications, and design constraints.
- 2. Design.
- Includes outline definition, format
- 3. Implementation.
- Requires writing, editing, integration
of various components, and proofing.
- 4. Testing.
- Includes verification and evaluation
against the requirements.
Are you taking these steps?
But wait! There's another phase I call
Documentation Maintenance! It begins after you deliver your documentation to your user. You
can divide Documentation Maintenance into the following steps:
- ___ Determine need for change
- ___ Submit Change Request
- ___ Review Proposed Changes
- ___ Analyze requirements
- ___ Approve/Reject Change Request
- ___ Schedule task(s)
- ___ Review and Analyze Design
- ___ Write and Edit
- ___ Test
- ___ Verify against Standards
- ___ User Acceptance
In these steps, I outline the maintenance
process, which begins when someone
needs a change and ends when your user accepts your changes.
As you can imagine, changing documentation
is frequently complex and may involve many people.
For example, imagine the task of updating
documentation for applications in complex electronics,
aerospace, law, medical, insurance,
etc. Or, how about updating flight-prep manual for a commercial airliner?
The maintenance process above appears linear.
But again, you'll undergo many steps and iterative loops.
- You may need to clarify the Change
- You may require more analysis of the
- You may need to rewrite your Standards
- Your users may fail to accept the results,
Someone, the "Maintainer(s)" must do
This Maintainer must make changes within
the context of the existing documentation. Maintenance people often find this the most challenging problem.
The older the documentation, the more
challenging and time-consuming the maintenance effort. But
normally, maintenance takes you less time than development.
Do you schedule these types of maintenance?
Your development effort may span several
months. You may schedule PERFECTIVE maintenance
in cycles of one to six months. But, you may require CORRECTIVE maintenance within hours.
Functionally, you can divide documentation
maintenance activities into three categories:
- ADAPTIVE, and
Let me explain...
"Perfective maintenance" is when you
make changes,insertions, deletions, modifications, extensions, and enhancements
to improve understandability or maintainability.
You generally do Perfective maintenance
because you have new or changing requirements, or you may need to fine-tune the documentation.
Fine-tuning is an excellent way to introduce
a new writer to your documentation. This will reduce your chance of serious
Both failures and successes of your
documentation require Perfective maintenance.
- If your documentation works well, users
want more features;
- If your documentation works poorly,
you must fix it.
When you perform Perfective maintenance
on poorly written documentation, you can dramatically reduce resource requirements by making your
documentation more maintainable.
"Adaptive Maintenance" is when you
adapt the documentation to changes in the user environment. Environmental
changes are normally beyond control of the writer and consist mainly of
Rules, laws, and regulations that
affect the documentation. Typically you must quickly make these changes to meet dates established
by the rules and regulations.
Equipment configurations, such as,
new computers, new terminals, local printers, etc. Usually, you want to take advantage of improved features and/or pricing.
You normally perform this maintenance on a scheduled basis.
Data formats, file structures, etc. You may require extensive
maintenance if these items were not properly designed and implemented.
If you can isolate changes to specific modules, the maintenance may
have less impact. If not, the effort can be both lengthy and costly.
System software, operating systems,
compilers, utilities, etc. In these cases, you usually perform maintenance on a schedule.
"Corrective Maintenance" is when you
must fix errors - sometimes immediately.
Generally, you'll find three
types of errors:
These errors include incomplete or faulty
design because of incorrect, incomplete, or unclear descriptions,
or when the writer does not fully understand the user's needs.
Often, logic errors occur when user
instructions and/or unusual data combinations are not tested during
development or maintenance. These errors, usually attributable to
the designer or previous maintainer, include invalid assumptions, tests,
instructions, or conclusions, or faulty logic flow, and incorrect implementation.
The writer causes these errors. These
errors include incorrect implementation or design logic,
or incorrect use of special terms. While these errors may be
the result of negligence or carelessness, they are usually the easiest
NOTE: Many managers consider maintenance
to include changing specifications or adding new capabilities.
How to get what you want, when you want it.
Fascinating stuff, eh? As
I've said before, I'm a fanatic about documenting business processes. Find out for yourself! You have nothing to lose.
Together, let's document what you want,
how you want it, and when you want it. We will discuss various creative
approaches before the project begins.
partner in streamlining business.
PS. To receive the latest Profitable Venture Tactics eZine (free) click the button now.
* * * * *
* * * * * * * * * * * * * * * * * * * * * * * * *
(c) 2004 Mike
Hayden, All rights reserved. You may use material from the Profitable Venture
Tactics eZine in whole or in part, as long as you include complete attribution,
including live website links and email link.
Valley since 1984
take the pressure off.
9457 S. University Blvd. Suite 235
Highlands Ranch, CO 80126
Denver, CO: (303) 585-1945
© 2012 Mike Hayden All Rights Reserved Web Design
by Safari Studios