Boxes and lines

I once grumbled to myself that the engineers I worked with couldn’t have a conversation without “boxes and lines” — my shorthand for service blueprints, user flows, and the diagram du jour.

As the holder of an English degree, I revere good writing. I appreciate the sense of finality I get when a decision is written down. I love the clarity that documenting an existing process brings to a team looking to solve a problem they don’t yet understand.

And yet, experience has shown me the dangers of documentation, especially in a startup. When taken too far, documentation is costly, not just in terms of time wasted creating and maintaining something intended to change, but in the creation of an inferior product. How can it cause all that?

You make decisions too early

A thirst for documentation can force product decisions too far out to be useful or relevant. If you’re focusing on a service blueprint or an end-to-end user flow before product development has even begun, it’s easy to get hung up on logic you won’t be building for a month or more rather than focusing on the features in front of you.

This happens when a leader on the team doesn’t deal well with uncertainty. I’ve also seen it in organizations that think they are agile but really operate on a scrum cadence within a giant waterfall project. In both cases, documentation is seen as insurance against ambiguity. In reality, documentation papers over (pun intended) organizational or personnel issues. One colleague astutely observed that we had invented a process fix for a people problem.

How do you know you’re making decisions too early?

1. You spend as much time updating your documentation to keep it current throughout the development of a new product as you did writing it in the first place
2. You have to refer back to a “decisions document” to remember what was decided about scope or behavior because it was done so far before it was relevant

The cost of change feels higher than it is

We all know that the cost of change increases relative to the fidelity of a design. Product design and development is an iterative process that should involve some ideas hitting the cutting room floor. User interviews, user testing, and deeper domain knowledge should change the solution you eventually launch. That doesn’t mean you failed to design the right thing. It means you let users refine your intuition.

Companies that emphasize documentation inadvertently lock themselves into the earliest iterations of an idea. Once something is published, it’s visible for the company to see and may be referenced in client calls or influence another PM’s roadmap and product thinking.

Perhaps most damaging, it puts up a barrier to less-experienced PMs feeling that it’s ok to change their minds based on user feedback. Once a decision or design direction is documented, changing course can feel like admitting you don’t know what you’re doing. This hesitation is poisonous to the creativity of an organization and will make your product worse.

What signs indicate that your PM team is hesitant to go against their original documentation?

1. PMs drag their feet on documentation, for fear of being held to their initial scope, design direction, or other early design artifacts
2. Updates to documentation are seen as a failure by the PM to properly design a solution the first time around
3. Changes to user stories in the backlog are met with skepticism and a sense that the product is undefined, or a moving target the PM can’t pin down

Product managers rely on guesses rather than data

When you’re trying to make decisions on an aspect of a product that the development team won’t touch for several months, it means a couple of things. First, your product is too big and you need to see how you can distill the value into a smaller first version. Second, whatever decisions you make will be based on gut feel rather than data.

Sure, you can study your analytics and conduct interviews to loosely plan your product progression, but until you see how users interact with your v1, you won’t know what they truly need from v2 and v3. Specifying features and data flows at this stage makes everyone feel like they know how to meet a metric, but it doesn’t give the team the freedom to adjust to user behavior to actually meet the metric.

When are you relying on guesswork because data isn’t yet available?

1. You designed a massive feature/product/app and broke it into phases to give the illusion of an MVP. You don’t have time in your roadmap to react to user feedback to the MVP, because you had already scoped and designed phases 2 and 3.
2. Big picture thinking is shut down by team members asking for “boxes and lines” before they will engage in a conversation. A common sentiment is, “I need to review the documentation first, and then I’ll be ready to have a conversation.”

So when is documentation appropriate?

At the beginning of a project, to codify goals and success metrics.

I’m a big fan of Marty Cagan’s product development process, and particularly his Opportunity Assessment framework. My team relies heavily on this as a way of documenting the purpose of an initiative and how we will know we were successful. We refer back to the OA throughout a project to guide design, scope conversations, and tradeoff decisions with stakeholders.

Throughout a project, in the form of user stories.

The user story should be the source of truth about the agreed-on scope for a piece of work. The story can reference additional documentation, but those supporting materials should emerge as a story requires them, rather than sit in a wiki waiting for someone to need to review them.

At the end of a project, when you’re ready to start training and change management.

Internal documentation is crucial for training employees on new technology and equipping them to adequately serve customers. When you’re at the point of training employees on forthcoming features, it’s safe to document the new interactions. Create help desk pages, internal reference materials, FAQs, whatever your heart desires. Just don’t do it until QA is about to sign off on the release.

***

Documentation is a powerful tool for PMs to unify a team around a common goal, teach and train employees and users, and reflect on the learnings from a project. If the examples above resonate with your current experiences, take a moment to identify the key proponents for documentation and their motivation. Address the concerns in a more appropriate way, and your team will be freed up to make just-in-time decisions with the most up-to-date information available.

***

This article was originally published on Product Management Insider.