The Wisdom of Jim Gray: “It Doesn't Exist Unless it is Written Down" (part 2)

My old boss, Jim Gray, drilled into me the rule that “it doesn’t exist unless it is written down.” As I described in part one of this post, I eventually came to internalize this value and apply it to our distributed team at Trōv.

Distributed teams have a special need for writing things down. During most of my tenure at Microsoft, I was the guy from California trying to work with a team at the Redmond mothership, and most of the time that team had a hallway culture. Q: How do you learn to use the team’s framework? A: Walk down the hallway and ask Joe. Q: How do you configure your service? A: Walk down the hallway and ask. Some of it was written down, but not enough. I recall flying up to Redmond to attend a training session. They handed out a list of instructions to create the “hello, world” of the platform we were learning. I got really stuck and raised my hand to get some help from the guru. It turns out there was a whole other set of unwritten instructions that everyone else in the room knew. They knew because they were on the team and had already learned it from the hallway. “How was I supposed to know that?” I asked the guru. He just looked at me like I was dunce and shook his head.

At Trōv, there is no hallway - at least not for engineers. I’m the only member of the entire engineering team in the office. Everyone else is remote, spread out from Melbourne to Madrid. So we need to write things down. Our GitHub wiki is loaded. We have Google Docs for material that needs to be shared with non-engineers. We have conversations saved and searchable in a number of places. We make sure that our APIs deploy with their documentation.

“Over-communicate,” is my challenge to our team. “Send too many emails, write too many wiki pages; we’ll let you know if it is getting to be too much.”

It never has.

Now, there is a possible dark side to writing things down. I’ve seen cultures where writing is the only output: endless slide decks, white papers, and emails - and no impact. Or places that insist on lengthy specifications, redundant comments in code, or detailed plans/projections beyond the foreseeable future. Three key concepts help keep us away from the dark side: (1) write to actually serve someone (2) let the tools do the work, and (3) write good, well-tested code.

When you write to serve someone, you aim to fill a need. For instance, we write down postmortems of our production issues to help the reader in the future, whether it be someone looking at a similar issue, or someone looking for the big picture and trying to improve our stability in general. We write down coding guidelines, design principles, and test strategy to help everyone deliver consistently and get new hires up to speed. Infrastructure setup, examples of library usage, and API documentation ensure that anyone can understand and use any part of the stack. Any time someone asks “how do I ….?” or “where do I find the information …?”, it is a signal that we may need to write something down to serve them.

Thankfully, we live in a wonderful time of tools that naturally document for us. Agile planning tools automatically document your work and your progress. Trello has our current high-level plan and captures our history. Pivotal tracks our stories and we use it to attach a conversation to a story. Our conversations in Slack are searchable and organized into channels. Github documents our commit history and code reviews, and also provides a nice forum for issue discussion and tracking. Using these tools in the right way satisfies "write it down" as a side-effect.

Finally, maintainable, well-tested code is also a communication medium. When you write an acceptance test or unit test, you have written the best spec of all: an always up-to-date one that clearly describes both behaviors and corner cases. When you adhere to guidelines to make code readable, including the right sort of commenting, the code itself becomes its own best description.

So write it down! Who knows, maybe it will help another future Turing award winner to be discovered.