 |
Further
Reading ...
|
|
How to Grow Your Business using Nature's Secrets - Syd Stewart
Nature has no grand plan, no long-term plan, no vision statement, no foresight, no mission statement, no manifesto, and no long-term objectives. Yet, in nature, complex, powerful, elegant, awe-inspiring, incredibly capable organisms and species...
What? Me Start a Home Business? - Rudy Cline
Most folks in the workforce dream at one time or another of starting their own business. Have you ever heard the phrase "You need to fire your boss"? Many of us would like to do that! Yet when it comes right down to it, most will never venture to...
No Pain, No Change - Susan Carter
No Pain, No Change Implementing changes, even when they’re good for your business, can be tough. As the old adage goes, old habits die hard and it’s just as true in business as it is in our personal lives. It’s simply easier to take the path of no...
Lets consider a Personal Loan - Tony Forster
Back in the days where banks were the only lenders in the business, getting a loan meant putting on your best clothes to go to a nervy appointment with the bank manager. You'd sit there for some minutes, feeling like you're facing the school...
|
|
|
Are you maintaining your documentation correctly?
|
 |
Written By:
Mike Hayden
|
|
|
============================================================
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 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
universe.
"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 -
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
control it.)
"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 definition, etc.
3. Implementation.
Requires writing, editing, integration of various
components, and proofing.
4. Testing.
Includes verification and evaluation against the
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 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.
For example,
You may need to clarify the Change Request.
You may require more analysis of the Design Reviews.
You may need to rewrite your Standards Audit.
Your users may fail to accept the results, etc.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Someone, the "Maintainer(s)" must do the work.
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.
Your development effort may span several months. You may
schedule PERFECTIVE maintenance in cycles of one to six
months. But, you may require CORRECTIVE - continued below ...
|
|
|
continued ...
maintenance
within hours.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Functionally, you can divide documentation maintenance
activities into three categories:
PERFECTIVE,
ADAPTIVE, and
CORRECTIVE.
Let me explain...
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
PERFECTIVE MAINTENANCE
"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 errors later.
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
"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 changes to:
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
"Corrective Maintenance" is when you must fix errors
- sometimes immediately.
Generally, you'll find three types of errors:
Design 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.
Logic errors.
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.
Writing Errors.
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 to fix.
NOTE: Many managers consider maintenance to include changing
specifications or adding new capabilities.
Fascinating stuff, eh?
============================================================
5. Call to Action
============================================================
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.
Mike Hayden
Principal/Consultant
Your partner in streamlining business.
About the Author
Mike Hayden is Founder/CEO of Senior Management Services and the Documentation Express in Silicon Valley, California. Mr Hayden is the author of "7 Easy Steps to your Raise and Promotion in 30-60 Days! The book that smart bosses want their employees to read."
ISBN 0-9723725-1-2. More articles at http://www.SeniorManagementServices.com/pvt-information.html
|
|
|
|
 |
|
|
| _Additional Resources ... |
|
FOCUS on Your Business Program. Power of FOCUS. - Raymond Johnsen
If you are anything like me, you probably find yourself often thinking of new projects to start, new things to achieve. I did that in my beginning on Internet. That in itself is very beneficial and indeed a required ingredient for success. The...
Get real about Home Businesses!!! - Michelle Cornes
Copyright 2005 Michelle Cornes Are you thinking it might be time to take control and work for yourself? The degree to which YOU are up for this challenge is everything. Here are some of the things about yourself that you really need to be...
Recommendation Letters Demystified - Shaun Fawcett
Recommendation letters are often referred to in a number of different ways including: letters of recommendation, reference letters, letters of reference, commendation letters, and sometimes even, performance evaluation letters. This terminology can...
|
|
|
|
|
|
|
|
|
|
