|
||||||||||||||||
|
How do you know when your documentation is done?CONTENTS:
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.
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 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:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Poor Writing A lot of documentation is poorly written because the writing effort was undisciplined and unstructured, causing:
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.
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:
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.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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.
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." Mike Hayden Principal/Consultant, Your partner in streamlining business. PS. To receive the latest Profitable Venture Tactics eZine (free) click the button now.
RETURN TO * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * (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.
We take the pressure off. | Home | Who we work with | How we work | Client Services | | Client Results | About Us | Contact us | Senior Management
Services |
|