David Tuite

The simple value of writing down the problem

June 09, 2018

a pencil against some paper

Value 1: It keeps everyone on the same page

How many times have you been in a meeting discussing a solution or a status update and the following happens:

Stakeholder 1: "This solution will easily scale to 1GB a week"
Stakeholder 2: "Right but we need something which can handle 10GB per week"
Stakeholder 1: "Are you sure? We recorded 1GB of stuff."
Stakeholder 2: "No I'm fairly sure John told me it was 10GB."
Everyone: Facepalm

Don’t spend your time going back and forth like this. Use your document as the source of truth (that means… KEEP IT UPDATED) for all the parameters of the problem, share it on the screen in the meeting and help everyone move onto the important stuff.

Value 2: It gets people up to speed quickly

Not everyone who might be involved in bringing a feature through to completion will be expert level on the problem space.

For example:

  1. A security engineer might have to review it
  2. A legal person might have to sign off on it
  3. A networking engineer might have to firewall it

Lots and lots of people are involved when you’re trying to solve a complex problem in a large organization and they’ll each have their own slice of knowledge of the organization. When you have a document with a diagram and a description of the current state of affairs you have the ability to let anyone read it for 5 mins and know enough to give you their individual perspective.

Without it, you’ll have to verbally describe the situation 10 different times to 10 different people and you’ll leave out details and make mistakes.

Even worse, people will hear about the problem second hand with many missing details and form their own opinion based on mistaken information. When you have a document to point to you can nip this in the bud.

Value 3: It records history

Most good document stores have some type of versioning these days. Confluence has it, Google docs has it, I’m sure many other products have it.

You can use these documents like a living history store where you can go back and figure out when you learned a specific piece of information (because you added it to your document right!?) when you changed your mind about something or whatever you might need to remember.

Writing things down in the document makes it easy to go back and construct a timeline of the project from start to finish.

David Tuite

Written by David Tuite who is a product manager at Workday and used to be a software engineer. You should follow him on Twitter