Throw It over the Wall

  • Anecdotal Evidence:

    The Code is finished (no testing, no documentation).


Rarely is documentation entirely self-explanatory, yet understanding the vision and insight of the authors is an essential part of understanding the documentation. This is especially true of guideline documents, where there is an implicit assumption of independent decision making. This assumption also implies an in-depth knowledge of the authors' intent.

By its nature, all human knowledge is personal. Even the most eminent scientists possess a personal insight that drives their discovery and articulation of new information. Understanding this personal insight is essential to understanding their work.

AntiPattern Problem

Object-oriented methods, design patterns, and implementation plans intended as flexible guidelines are too often taken literally by downstream managers and OO developers. As guidelines progress through approval and publication processes, they may be attributed with unfulfilled qualities of completeness, prescriptiveness, and mandated implementation.

Such literal interpretation of flexible guidelines can lead to unintended results. Decisions may be made based upon guidelines that were intended only to inspire careful analysis and locally optimized decision making.

For example, effort may be wasted on useless analyses and documentation because it appears mandated, although nobody on the development team understands its purpose. This phenomenon happens in both large and small organizations and may be due to miscommunication between development phases. Another important cause is the desire to satisfy the apparent expectations of management instead of the needs of the system's end users.

Refactored Solution

In order for technical documentation to be interpreted and implemented as intended, the material must be communicated through several important techniques. One is to deliver the knowledge through a tutorial. Whenever new policies and guidelines are established, there should be a corresponding transfer of information to promulgate the information and communicate the motivations.

We have found that a one-day training session is usually sufficient for development specifications of up to 100 pages. It may, however, be useful to conduct the session in two parts: a management introduction and a technical briefing for developers, as these two different audiences have substantially different needs.

If you combine these groups, the management discussion often extends into the time needed to cover the technical details. Follow-up support, including telephone and electronic mail contacts, is useful to ensure successful technology transfer.

Read next