Introduction

I saw some things posted on LinkedIn regarding documentation, and it got me thinking. The adoption of Agile approaches has encouraged the elimination of documentation. To be sure, there are times when documentation is perhaps heavy-handed. However, that does not necessarily mean abandoning project documentation is a good idea. Swinging into either extreme direction will not be helpful.

Our organizations have always been looking for the latest trends or approaches that will enable the company to quickly reach their objectives and goals. If you have read Dilbert comics, you will note this to be a priority to the limit of absurdity. Faster. Less expensive. Lean. All are priorities to maintain the business case for the effort and company viability. This leads us to Agile. I have heard team members say we do not need to do a particular thing because we are using Agile. That is not a productive approach to the work. Our approach to the project documentation, or work in general, should be commensurate with the scope, organization strengths and weaknesses, and risks associated with the project.

What are the benefits of documentation?

As much pain as documentation may be, it has some benefits. Let’s look at a few.

Clarity and Consistency

Documentation references provide a clear and consistent framework for understanding project requirements, processes, and expectations. Documentation makes traceability possible. We have a reference for all team members when we document things like the project scope to interpret based upon constant articulation. In other words, it is not based on word of mouth. Team members can refer to a centralized source, reducing ambiguity and ensuring everyone is on the same page. It is not a game of telephone subject to a pipeline of articulation. Relying on obsolete information may result in misinformed decisions, project delays, rework, and cost overruns. This clarity will help with dispersed teams and team members who are non-native language speakers.

Knowledge Transfer

The treasure trove of documentation serves as a valuable resource for onboarding new team members. We cannot rely solely upon this documentation, but it provides a base from which further questions and clarifications can be explored. Additionally, documented processes and procedures facilitate knowledge transfer, allowing new team members to get up to speed quickly.

Historical Record

Documentation creates a historical record of project decisions, changes, and outcomes. This historical record provides an explanation of sorts for the project status or outcome. Otherwise, we attempt to reconstruct what happened using our memories and biases. There will be little evidence for us to walk through what happened that led to the outcome.

I watched a show on The Smithsonian Channel called Aircraft Disasters. I do not watch these out of some macabre fascination but out of a desire to learn what is required to perform a root cause analysis of a problem. It is not easy. If you want to learn about this, I encourage you to watch a few episodes to understand the ancient Greek legendary Gordian knot that is root cause analysis. If you watch, you will see the value of documentation in many forms, from paperwork leading up to the flight (loading and manifest) to cockpit voice recordings and flight data recorders.

This historical record can be instrumental for future projects, offering insights and lessons learned to improve efficiency and effectiveness. This will be helpful for the planning of subsequent projects, especially those projects that are similar.

Compliance and Auditing

Documentation is crucial in ensuring compliance with industry standards and regulations. It is tough to audit and ascertain compliance from word of mouth. Internal or external auditing will require more than word of mouth. Compliance and auditing will consist of reviews of documentation and other artifacts a project can produce. Documentation serves as a basis for audits, helping organizations demonstrate adherence to guidelines and quality standards.

Dependencies for Documentation:

Project documentation often is used by those outside the project. This common story illustrates the point. A product development project has documentation to define and guide the development of the product. The documentation is also used as the starting point for aftermarket documentation, such as repair manuals, and vehicle documentation, such as features and performance. The project does not keep the documentation congruent with the development work impact on the vehicle components and systems. The aftermarket documentation reflects this disconnect. Years after the launch, customer interviews reveal that the customer is unhappy, saying the system is overly complicated and the manuals are not helpful.

What are the Downsides of Documentation?

Like many things, there are downsides to creating and maintaining documentation.

Overemphasis on Documentation

Excessive reliance on documentation may lead to a bureaucratic environment, where processes become rigid and hinder adaptability. This overemphasis on documentation can cost us time, where everything requires a high degree of rigorous documentation.

Teams might spend more time creating and updating documents than on project tasks. Documentation is not always vital to the project or product development effort. Or at least it may seem like documentation is not essential; if you do not see the total range (downstream) of use of that documentation.

Outdated Information

In dynamic project environments, documentation can quickly become outdated when requirements and other associated documentation change frequently. Efforts to keep documentation congruent with the project and product actions can be significant.

Figure.1 Random pattern from water flow on Jockey's Ridge dune

Figure.1 Random pattern from water flow on Jockey’s Ridge dune

Lack of Creativity and Innovation

Strict adherence to documented processes may stifle creativity and innovation. An emphasis on formalism may dampen lateral thinking. From experience, lateral thinking is often essential to problem-solving and intellectual property generation. Teams might feel constrained by predefined guidelines, limiting their ability to explore new approaches and solutions.

Documentation Overload

A plethora of documentation can overwhelm team members, making identifying critical information and needed updates challenging. Mechanisms for tracking the latest versions or revisions of the documentation can add to this documentation burden. Sorting through excessive documentation may lead to confusion and inefficiency.

Attributes to Consider When Deciding on a Documentation Approach

Our advice on the documentation approach for each project will depend on factors such as those below. These things are worth considering regarding documentation strategies and tactics.

Degree of industry and legal regulation
Risk of the project outcome to customers of the field
The consequences of project failure and product of project failure on the enterprise
Project risks (consequences on scope, cost, and schedule)
Contractual obligations and stipulations
Project team distribution and primary speaking language
Depending on portions of the organization (manufacturing and aftermarket, for example)
Potential post-project legal entanglements (required demonstration of due diligence in court)

Conclusion

Regarding documentation or most anything related to project and product efforts, we are reminded of Chesterton’s Fence. This principle suggests we should not remove an activity or change a process (remove a fence) without knowing why those things are in place, and before deciding on the strategy for what to document and how to maintain documentation. Striking the right balance is key, recognizing the importance of documentation while avoiding unnecessary bureaucracy. Project managers must navigate this terrain judiciously but not alone. They must work with project sponsors and the domains (by team members) included in the project. Documentation should enhance clarity, consistency, and knowledge transfer while remaining agile and adaptable to change. Ultimately, the true treasure lies in a dynamic equilibrium where documentation is a valuable tool rather than a hindrance to project success.

dynamic equilibrium

To Document or Not to Document: That is the Question.