Short-Sighted Approaches to Documentation

Bookmark and Share

Solution development work is usually accomplished via projects, or a combination of programs and projects. This project perspective often leads to thoughts of documentation as project-owned. And while many documents are project-specific, such as  timelines, resource plans, and such, not everything is project-specific. Unless projects are established in a fashion whereby each is very limited in scope to the creation or enhancement of a single application or system, specification and design documents belong to the final solution and not to the project.

Many organizations ignore this relationship and create circumstances that result in scattered design details. Based on the pre-existing documentation regarding how a particular solution is supposed to work, in order for someone today to determine what these scattered design details mean, they would first need to uncover every project that ever touched the modules comprising the solution. Then they would need to track down all of the documents from all of those projects, read through them all in chronological order, and then maybe they would have a complete picture-depending on how well those documents were put together each time. Of course, if there were additional "maintenance" changes made over time outside of the context of any given project, an accurate picture might still be missing.

Because of the above circumstances, much of the time when starting new projects we are still in the dark ages. Those persons coming in to work on new enhancements and build on the past must track down the subject matter experts that "know" the system. Sometimes, these knowledgeable individuals are business-based, other times they are systems-based; what they know is simply what they know and that knowledge may or may not present a complete picture. Complete or not, the issue is moot; it is the best picture that can be made. This sharing of the oral tradition becomes the start of the new project, which builds new project-based documents that will certainly help with the short-term project work but will not leave the organization with the process documented as part of an ongoing repository of organizational solution knowledge.

How does one change the ongoing documentation myopia that is described here? It changes once development teams can focus on the endgame. Where and how should all of this knowledge be stored in order to be of value across the organization? What is a coherent taxonomy to describe the business functions and solutions for access?  Where is a good place for such information to exist? Getting a solid start on these questions is ideally a project unto itself. And, in some ways, a repository describing the business and the solutions is a "field of dreams"; build it and they will come. Set it up so that people can understand where things fit, so that as a project starts they can see how the things that they will describe fit into the repository, and they will help shape the documentation to fit. When a repository of solution truth exists, it quietly assumes an important role. Without that picture, what the project needs today is truly all that is allowed to be seen or understood.

This confusion over project versus product documentation is a natural by-product of our development practices. Anxiety rules project management, driven by a sincere concern that development costs too much and takes too long. Ultimately, the constant pressure-to-complete reduces costs by minimizing time for documentation. What documents are created are created quickly and are focused on the immediate change rather than a holistic picture. Superficially, these time cuts can save budget dollars, but those savings are only for today's budget. Tomorrow's budget is frequently saddled with the higher costs for learning every system all over again.