============================================================ Are you maintaining your documentation correctly? ============================================================As I've said in many 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!"
"Not really."
"Then what...?"
"I don't love writing per se. I love
applications. I love results. In writing, you can create, let's say, first level of reality. By writing, you can begin to give intangible ideas form in physical universe.
"Can you imagine how many people discovered secret of fire and didn't write it down? The news had to spread by 'tribal knowledge!'
"How many times did 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 - over and over!
"Eventually, I suppose, someone wrote 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 secret of fire and how to control it.)
"Mike, what have you learned over 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 following:
1. Requirements. Includes definition, statement of goals, preliminary analysis, functional specifications, and design constraints.
2. Design. Includes outline definition, format definition, etc.
3. Implementation. Requires writing, editing, integration of various components, and proofing.
4. Testing. Includes verification and evaluation against requirements.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 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 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 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.
For example,
You may need to clarify Change Request. You may require more analysis of Design Reviews. You may need to rewrite your Standards Audit. Your users may fail to accept results, etc.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Someone, "Maintainer(s)" must do work.
This Maintainer must make changes within context of existing documentation. Maintenance people often find this most challenging problem.
The older documentation, more challenging and time-consuming maintenance effort. But normally, maintenance takes you less time than development.
