Skip to main content

Get Off the Documentation Hamster Wheel

In a recent BA Times article, I suggested that most teams spend too much time on documentation.

I even boldly proclaimed: “When planning, elicitation, and analysis are done well, documentation becomes simple and speedy.” I think most people agree in theory. They are hungry to reduce documentation and speed up their requirements process, but they keep on documenting. They stay in the hamster wheel and keep writing and reviewing and updating their documents over and over again.

WickOct 1

Related Article: Are Business Analysis Documents Becoming the Dumping Ground?

Reducing documentation is a real struggle for individuals, teams, and organizations. They want to jump off the wheel, but they don’t know HOW! They ask me:

• What should I be documenting? What should I remove from my documentation?
• How do I know when it’s good enough?
• What does lightweight documentation mean?
• How will my developers get the code right if the details are not in my specs?
• How do we know if all of the requirements have been met if the documentation does not include detailed requirements?

Or they point fingers:

• The PMO/BACoE/CIO makes me fill out all of these templates.
• This is what the stakeholders expect.
• Audit requires all of these details.
• Legal wants this paperwork.
• The local/state/federal/international/alien planet government needs these documents.

Two New Mindsets

That hamster wheel is going to kill you (or more likely, stunt the growth potential of your organization)! Solving your document dilemma requires two significant changes in mindset. First, teams need to let go of “one size fits all” and replace it with “adapt or die.”

Every project has unique documentation needs. It’s ineffective and inefficient to apply the same approach to every project—teams need to adapt. Would you document a pizza delivery app the same way you document a life-saving medical device that will be implanted in a human body? No. Even within an organization, documentation approach should vary for internal vs. external users, new products vs. upgrades, bug fixes vs. major releases, process-based projects vs. system-based projects, etc.

While it’s important to adapt your approach, great requirements can be consistent! Consistent in explaining (without vague and mushy words) who the users are and what goal they are trying to achieve. Consistent in providing what context, data, rules and quality expectations are in play to create value for the end user and customer.

That leads us directly to our second (and most important!) mindset—teams need to “Let Value Be the Judge.” Instead of pointing fingers and passively accepting status quo, VALUE should be the judge of every proposed piece of documentation.

More is not better! We should identify the right requirement set: does this provide value, what is the thinnest/lightest version of documentation we can use to deliver value, will these requirements lead to a solution that over or under-delivers on value to the customer?

5 Factors to Evaluate Documentation

Consider these factors to evaluate each piece of documentation:

User: Think about who will be using the documentation and how they will use it? What level of detail do they really need? Discuss documentation reductions with users and experiment.
Lifespan: Consider how long the information will be used and how long it will remain accurate. Is the lifespan so short that the document provides zero value? Is accuracy so important that the document should be created just in time? Should the format of the documentation change based on the lifespan?
Cost: Think about who would be willing to pay for this information and why. Estimate how much it will cost to generate the documentation and determine if the cost aligns with the value. Is the process to create shared understanding of requirements more valuable than the document itself?
Fear: Explore the possibility that fear motivates excessive documentation (aka Cover Your A**?) Does that fear-based mindset boost solution value or does it increase time and cost?
Format: What is the most efficient format to deliver value? Do your requirements really need to be written in a template? For some, yes! For others, no. Do they really need to be entered into a tool? What is driving the template or tool usage, governance or better requirements? Depending on your project type and your team structure, documentation might be post-its on the wall, drawings on a white board, prototypes, notes on a napkin or even a series of discussions/demonstrations.

Above all, strive to create an environment that allows for constant collaboration and meaningful dialog with developers. Change the mindset that thinks requirements are DONE when we hand them off to our techies. Instead, be in it together from start to finish.

But What About Audit?

I am not suggesting that you ignore or refuse to cooperate with protective entities like legal, audit, best practice (Center of Excellence/PMO) and regulatory. Instead, I encourage ongoing and collaborative conversations about documentation. Understand what they need and why. Work together to determine the thinnest/lightest version of documentation to meet their needs.

Are you ready to jump off the documentation hamster wheel? Instead of spending all your time updating requirements and managing sign-off, focus on helping your team think strategically about the value you are providing to end users and the organization. Details fall into place with minimal documentation when teams collaborate continuously. Conversations rooted in value build shared understanding, which alleviates the need for excessive documentation.

Please leave your comments below.