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


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.

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


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.

Transformation Corner is authored by members of Value Transformation, a team comprising seasoned project managers with extensive backgrounds in various industries including government, construction, automotive product development, manufacturing, and IT. With decades of collective experience, our team members bring a wealth of expertise to this column. Authors: Steve Lauck Shawn P. Quigley Jon M. Quigley Rick Edwards Ashley Taylor Womble Jon M. Quigley, holding PMP and CTFL certifications, boasts nearly 30 years of product development experience. Specializing in process optimization, quality enhancement, and cost reduction, Jon's expertise spans embedded hardware and software, verification, and project management. He is a recipient of the Volvo-3P Technical Award (2005) and the 2006 Volvo Technology Award. Jon has secured seven US patents and numerous international patents, and co-authored over 10 books on project management and product development topics such as agile methodologies, testing, and configuration management. He has contributed to various publications, including works like the Encyclopedia of Software Engineering. For more information, refer to his LinkedIn profile.
Share This Post
Have your say!
  1. I have been involved in Claims work, wherein an organization has had a claim made against it and it has hired my firm to review the claim. All to often we begin our review of the organization’s files and find out that there is not enough documentation prepared or retained. Please document your actions, explaining what you did and why you did it. Remember the “W”s What, Why, When, Where and hoW.

    • Good advice. I like to use the word objective to help clarify why we are doing a thing and perhaps how (given constraints and assets) we should do a thing. Projects are not operations where we have perfect knowledge and control.

  2. I read with interest about your documentation overload.
    The first PM job I had was at Fisher-Price Toys and they were a Univac/Cobol shop with heavy documentation requirements on everything you did. Initially, I was overwhelmed and hated doing all their documentation. Within two years something strange happened to me – I was getting good at writing documentation and enjoyed doing it. Since then, I have had four books and over 75 articles published on project management and the systems development life cycle. I was able to turn the curse of documentation overload into an asset for me.

    • That is a fascinating up side of your efforts. I have seen documentation save a company in the long run. If you are building something that can harm folks if something goes wrong, demonstrating due diligence is important. Development teams that span the globe often require more documentation.

      Both of my advanced degrees were research and writing intensive. I credit those things for my hundreds of articles and 20 books. Thank you City University of Seattle.

Leave a Reply