Just Write It Down
Tags: discuss, career, productivity
Published: 2018-12-27 16:09:00

---
title: Just Write It Down
published: true
description: When writing down product specs meets engineering
tags: [discuss, career, productivity]
author: Gregg Meluski
date: 2018-12-27 11:09 -0500
---
*This post was originally published at [meluski.com](https://meluski.com/engineering/2018/12/27/just-write-it-down.html)*

If you want to know what brought me to the idea of creating one page product pitches, I would start with pain. More specifically it came down to choosing which form of pain I wanted to endure. Did I want the hot, burning intense pain of a missed requirement, gambling that we've somehow hit all our angles during the course of discussing our project requirements, or do I want the foggy, weird pain of backing out of my common routine and tacking on another preparatory step?

It's tempting to barrel forward and take the risk that we've got it all figured out without documenting our thought process. And maybe it's not the current project that has the hiccup, maybe it's the next or the one after that. The team may be honing in on release when someone says "well, wait a minute, why didn't we do [insert brand new thought here]?".

It seems like the proximity to shipping sends up a signal flare to tangential players in the project, the interested but busy, the partially invested. And due to their distance, they have a different perspective. And that can feel painful.

But you WANT that perspective, because the more points of view in the pool of product conceptualization, the better the product outcome. And what's painful is what has been spent on the personal, mental, emotional and even physical levels (yes, being hunched over a keyboard is a physical investment). Sunk cost fallacy? Sure, but there is real attachment to things that have already been built. 

There's the significant pain of having to reconfigure the mental model of how this particular feature works. It takes time to unlearn, to incorporate new information into the existing design.

So this foggy, weird pain of doing something new and different? Suddenly this is an acceptable trade off.

This pain is really a manifest of my selfishness, my belief that my current workflow is acceptable. I write things down on a pad, it's chicken scratch. I write unit tests, but that's not easily circulated to non developers. I have check ins with my team, however those are verbal and ephemeral - but anyone who has missed a meeting has missed the information included in said meeting. 

Gee whiz, when it comes to the most basic, essential, and easily digested form of communication and explanation, my mind body and soul resists. 

In order to close the gap between the concept of a product doc and an actual implementation, there are a few additional hurdles:

- If I'm going to write a product document, where does it go? 
- Are people going to read this? (aka am I shouting into the void, and if so, why am I wasting my time?)
- Is there some sort of structure to this, and what is it?

For starters, I like to compose locally and privately. I don't know what it is, but there is a feeling that when I am dumping out my initial ideas and organizing them, I don't really want to feel as if someone can look over my shoulder, digitally or otherwise. So I like to at least start with a locally stored (or personal, cloud-based) version that I can use for both refining and future reference.

I did stumble with how to make the document available for public consumption. An email with either the product document inlined or attached could be used as the thread to track comments on the product, but it does get hairy if people need to be looped in later. A shared Google Document will solve that issue and allow folks to do inline commenting in a bit more organized fashion. Personally, I feel any tool which enables circulation and an organized conversation will provide an acceptable outcome. 

I get so many things links and emails where I do quick scans and then forget. Maybe it's a signal to noise ratio thing - there's a lot of information going around in a company of any size, and sometimes the decision as to what is critical and what is deletable is a snap judgement. But there are certainly things that I care about, especially things that effect my own work. There's a lot to explore when it comes to keeping people informed without overwhelming them, but in this case I did the manual work of making a `People` section in the document and thought through who might actually care about this project.

I'd like to throw this thought in before proceeding - writing the document itself is informative for the writer, even if no one else reads it. 

For a document of this nature, having a templated structure can make it easy to get started the next time. After bouncing around some saved articles in Pocket and looking at some of my previous (failed) attempts at this approach, I landed on the following headings. This list is broad and there is potential overlap between topics, but in my opinion it is more efficient to eliminate and combine sections as I write than to have to create a section heading and reorganize. Hopefully this list helps anyone stumbling around the vagaries of product write ups:

```
Problem Definition
Wider Context
Goals
Scariest Assumptions
Unknowns / Issues
How Will This Be Tested?
Is There Effort / Approval Required From Other Teams?
How Will We Measure Success?
People
```

It's still too early for me to determine whether this is an effective organizational practice, especially since I was originally solving for the siloing that came with a recent technical reorganization. 

Time will tell? For now, I'm happy to reap the benefits of self-organization that come along with it.