Senior Management Services
Purging nightmares from business dreams.

       

 

How do you know when your documentation is done?

CONTENTS:

1. When do you assume that your documentation is done?

2. What are the TECHNICAL PROBLEMS?

3. What are the MANAGEMENT PROBLEMS?

4. Where can you go for help?

1. When do you assume that your documentation is done?

I've been updating our website... What a time-consuming horror show!

Years ago, I put up the website with no plan - it was just an experiment. Meanwhile, the website has grown to hundreds of pages with over 40,000 links...

Anyway, this brings to mind the topic of maintaining documentation...

Eventually, we need to maintain documentation, whether it's paper, computer files... or a website.

Some companies strive to improve all their documentation.

But usually, individual writers or managers make improvements by using modern practices such as modularization, top-down design, peer review, etc.

We find that few companies uniformly adopt modern methods. Most companies lack practical guidelines for developing and maintaining documentation.

"[...] I think one of the biggest mistakes [...] is wrongly assuming that documentation is something that ends at some point. In reality, [...] documentation is never really complete."

--Chad Dickerson, InfoWorld Columnist, July 11, 2003

However, we can trace most problems to poor management of the basic documentation process. We see both TECHNICAL PROBLEMS and MANAGEMENT PROBLEMS, which I discuss below.

2. What are the TECHNICAL PROBLEMS?

Below, I divide technical problems into several areas. I will address them one at a time.

  • Poor quality,
  • Poor design,
  • Poor writing,
  • Lack of common definitions, and
  • Documentation designed for outdated systems.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Poor Quality

If you ignore quality during design and development, you'll always see higher maintenance costs. Quality directly affects maintainability.

To minimize poor quality, we must give structure and discipline to developing and maintaining documentation. This helps us eliminate many problems for new documentation. Still, it does not solve problems with older, unstructured documentation.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Poor Design

We must use good design specifications. We can attribute poor documentation to:

  • Misunderstanding user needs
  • Lack of design discipline
  • Misinterpreting design specifications
  • Using complex logic to meet simple requirements
  • Disjointed segments that don't fit an integrated whole
  • Large, non-modular manuals that are unwieldy and difficult to understand (worse, a large manual with no specific modules)

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Poor Writing

A lot of documentation is poorly written because the writing effort was undisciplined and unstructured, causing:

  • Confusing jargon and procedures
  • Poor formatting
  • Lack of cross-indexing
  • Large, poorly structured modules
  • Lack of project notes (AKA project documentation)

You know how infuriating it is to try to understand poorly written documentation. If people with multiple writing styles wrote it -- it's even worse.

Often, we find poor writing that is "usable" but difficult to use.

  • Sometimes it's not suited for the reader's skill level.
  • Sometimes it's plain unfriendly.

Changing poor writing can be expensive!

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Lack of Common Definitions

Invariably, when two or more writers independently write sections, they create definition conflicts. This causes sections that do not logically relate.

Manuals, whether large or small, must employ common definitions throughout the manual. Also, you should specify the information structure for all modules.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Documentation Designed for Outdated Systems

Rapidly changing technology causes growth of new documentation. You'll discover many problems when you try to maintain documentation designed for outdated systems.

You'd like to throw it away, but... it would cost too much to rewrite. So, you must maintain it.

Your first problem may be to find willing and able maintainers. Why? Few "good writers" are willing to work on outdated documentation. The required skills are not relevant to other career possibilities.

Writers know that working on outdated documentation limits career advancement. Worse, most outdated documentation is difficult to maintain.

3. What are the MANAGEMENT PROBLEMS?

Below, I discuss some of the management problems, which include excessive resource requirements, lack of project documentation, user problems, and stubborn personnel.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Excessive Resource Requirements

We find that most maintenance (especially enhancements) requires increased resources. Often, your maintainer cannot determine the best solution for required change(s).

Often, the maintainer simply "patches" changes into the documentation... but this compounds future problems and resource requirements.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Lack of Project Documentation

We find that one of the major problems in maintenance can be summarized by, "a failure to communicate." Here's why:

The person receiving the maintenance assignment must have access to project documentation such as written specifications, comments, notebooks, and other project documentation. (Rare indeed!)

Too often, maintainers receive little or no communication from those who previously worked on the project:

  • NO specifications!
  • NO records of requests and updates!
  • NO explanation for complex logic and structures, etc.!

This breakdown is further hampered if the maintainers don't speak the same jargon or understand basic requirements.

Worse, months or years pass between original development and subsequent maintenance. People who developed the original project have top-toed silently away.

Thus, you must develop good project documentation AS YOU GO! The more complete and clear the project documentation, the easier the maintenance.

"Fortunately, the weblog paradigm gives ... the means to create documentation that works the way people think - in dates (when did this happen to the system?), incidents (what happened, and how was it fixed?), and people (who fixed it?). [...] This [weblog] method of group documentation works better in practice than anything I've ever seen. [...]"

--Chad Dickerson, InfoWorld Columnist, July 11, 2003,

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

User Problems

Users are often unable to specify exactly what they want.

So, initial specs often lack details that enable writers to create documentation that satisfies user needs. Thus, companies often place incomplete documentation into production!

Later, someone must enhance the documentation using inadequate specs -- plus new, incomplete change requests.

Even when documentation is well implemented, users want new features. Therefore, managers must establish and enforce controls to justify change requests.

Change requests that are excessive, conflicting, or vague have a major impact on maintenance. Users typically don't know how even one change affects the maintenance workload.

We find that the number of change requests is usually proportional to the success of the original documentation (and its maintenance). You must carefully review change requests to control maintenance costs and consequences.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Stubborn Personnel

Maintenance people complain that maintenance is considered unimportant, unchallenging, and unrewarding - and not appreciated by users or management.

Still, we find that documentation maintenance requires experienced, well-qualified professionals. You should avoid giving it to new or junior staff. With more complex systems, you need maintainers who can understand the entire system.

Traditionally, management does not reward maintainers as generously as developers. They assume that analysts, designers, and developers are responsible for the most difficult tasks. Therefore, they are more capable.

While this is a common attitude, management is increasingly aware that maintenance is important to successful, smooth operations.

Meanwhile, many technical people avoid maintenance. Why? They are not recognized as skilled persons concerned with both assessing the effect of changes and fulfilling those changes.

"[...] One problem is simple: documentation [...] for production systems is usually an organic beast. However, most developers and systems administrators finish a project and quickly put it to bed, sometimes without any documentation. Many times, I have scanned a particular system's documentation during a crisis only to find that it had not been updated in several months (or even years). Small and undocumented changes can add up to large, undocumented messes. [...]"

--Chad Dickerson, InfoWorld Columnist, July 11, 2003,

4. Where can you go for help?

Don't let the lack of documentation maintenance stunt the growth of your business!

We can help.

For more on this subject, read "15 Expensive Mistakes Managers make in Developing Business Documentation."

mh

Mike Hayden Principal/Consultant, Your partner in streamlining business.

PS. To receive the latest Profitable Venture Tactics eZine (free) click the button now.

Subscribe!

 

return to free articles

RETURN TO
FREE ARTICLE

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

(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.

rainbowrule

Senior
Management
Services

Typical SMS Clients

In Silicon Valley since 1984

We take the pressure off.


| Home | Who we work with | How we work | Client Services |
| Client Results | About Us | Contact us |

Senior Management Services
9457 S. University Blvd. Suite 235
Highlands Ranch, CO 80126
Denver, CO: (303) 585-1945
Email
© 2012 Mike Hayden All Rights Reserved • Web Design by Safari Studios

Page copy protected against web site content infringement by Copyscape

 
Subscribe!