Just Write It Down: Embracing Imperfection

The team at Living Spec has been working remotely for more than 15 years on various problems, and has consequently learned a lot along the way.

Dojo Toolkit

In 2004, Dylan Schiemann, CEO of Living Spec, co-founded Dojo Toolkit, an open source, JavaScript framework. Dylan and co-founder Alex wanted to define what Dojo should become. 

Dylan and Alex downloaded the first collaborative editor at the time, SubEthaEdit for the Mac.  They sat with their laptops back-to-back at a coffee shop, in Mountain View, California, and over a few hours, wrote a list of 20-30 features and use cases. They published the list, and about two years later, everything on the list existed in some form in Dojo.

Improving Your Team’s Written Communication

At the same time, Nemanja Tosic, Dylan’s co-founder at Living Spec, was working on a large enterprise team, and would commonly receive specs from the business side that made for nice use case models. 

These models would come back to the development team and the project managers, and down the pipeline, everyone involved rewrote them in their own way. Some of the project managers used Excel while developers were keeping track of things on physical whiteboards. Everyone wrote their own information in their own way. 

This can make it challenging for any given team member to put the pieces of the project together, know where the information belongs in the initial system, and keep track of what has been done and what they should work on next. 

A 2022 study by McKinsey shows that poor coordination is killing a company’s abilities to adapt, and that roughly half of engineering productivity is lost by poor coordination. 

Poor coordination can occur for many different reasons. Sometimes you’re in the zone, ready to write code, but then you have more questions than answers:  What am I building? Why am I building it? Is this the right version?

Write it Down: Where, When, How, What 

Another question that often comes up is: Where do I write things down? How do I write information down? Which page does it belong to? What type of language, or what type of template? At this moment, the only thing you want to do is get an idea out of your head, but instead you’re immersed in the details and the mechanics. 

Many teams, for example, use Google docs for written communication, and have five or six documents all saying final, so no one actually knows which one is final.

This is all meant to illustrate that there are a lot of obstacles that get in the way of something as simple as just writing information down, one of the keys to success. If you write something down, there’s a much higher chance it gets done. 

Where to Write it Down

So where do you write important things down? Can you just tell someone directly, put it in Slack, or mention it on Zoom? Your information needs to be written somewhere accessible, where it can be read and edited over time.

The important thing here is to create a process so everyone on your team knows where to access the information and where to add new information. 

When to Write it Down

someone’s going to immediately tell them it’s wrong, or that they’re being stupid, or that it’s imperfect. This can make it hard to achieve anything.

Information needs to flow and the information needs to be accepted as opposed to being judged for what it is.

For example, GitHub has helped in this regard by introducing draft pull requests, allowing developers to add code without fear of judgment. Similarly, the Work in Progress (WIP) tag indicates that something is not ready for thorough review and scrutiny.

What to Write Down

Sometimes, it takes a couple of minutes to find a missing bit of information. You might not write it down or know which system you need to write it down within, or you may not know whom to share information with or why, or whose opinion needs to be heard on what changes.

These are some of the problems that need to be solved and questions that need to be answered. The good news is that there are tools to help with this process. 

How to Write it Down

While writing things down sounds pretty easy, it does take time to write things down most effectively and take what someone said and slowly think about it. It often helps to split information into small scopes with more specific context.

Tools like Living Spec help identify sources of friction for collaboration and strive to remove them by providing a collaborative document tree of pages, tasks, files, comments, people, and more.

Oftentimes, teams start small, and then the work evolves with iterations and becomes something bigger than hoped for. Information can be linked to multiple places, allowing a project to grow naturally, instead of putting data in a specific place and then never touching it again. 

By making it efficient to connect ideas together in the relevant place, teams can start to improve collaboration.  

Embrace Imperfection

It’s important to accept imperfection and allow a natural process to occur. The natural human process is messy. It might not be pretty, but you need to get your ideas out there. You have to get them out in front of people who can make suggestions based on what you wrote instead of keeping everything in your head and then trying to remember all the bits and pieces that need to go together. 

Having a process that allows you to get your information out of your head and into a system as fast as possible is key. If it takes three minutes to find the location where you want to enter something, you’re going to give up and resort to paper or Google Docs or notes apps.  

Have a streamlined, efficient process that doesn’t judge you. It helps you get your job done more effectively and embrace the messiness, iterate over time, and have confidence that you’re not losing information.

GitKraken’s suite of developer tools are designed to improve team collaboration and communication. Give our tools a try for free: GitKraken Client for the desktop, GitLens for VS Code, and Git Integration for Jira.