Last week, my engineers and I met to discuss the specifics (or so we thought) about a feature we were going to be working on. Even after an hour of healthy debate and discussion, I felt that everyone in the room wasn’t on the same page.
- the backend engineers thought they knew – down to the details – how they needed to structure what they’re going to build
- the frontend engineers assumed a certain structure for how the backend engineers would build their pieces, on top of which they’d be working on
- the new hires in the team were probably struggling to put pieces together based on our discussion
If we had actually gone ahead and built what we wanted to build without getting to the details in writing, it’d have been nothing short of a disaster.
For months, I had been asking my team to document our decisions and architecture, but I don’t think my team understood the value in doing it. The fact that they didn’t see it is probably on me. I was asking them to document things all the time, but I wasn’t really helping them understand why they should do it.
The next day, I brought them all together and showed them this tweetstorm by Steven Sinofsky. Steven uses a slide to illustrate how most details are lost when you convert thoughtfully written paragraphs into bullets. And how it’s difficult to grasp the depth of information that was originally shared, when you condense an essay into slides.
In our case though, it was worse than a deck – everything was verbally spoken about and things were completely up in the air. We assumed clarity, when clarity wasn’t there.
I told my team that if we had actually gone on to build what we were planning to build with assumed clarity, we’d have wasted time down the line. We’d have rewritten code later because we’d have built things based on assumed clarity, not based on truth that was agreed upon and communicated using crystal clear documentation.
A week later, everyone started seeing the value in documentation. It became obvious that if we really had to get everyone on the same page (pun intended), we had to get to the last bit of detail, and write things down. There was no way around it – discussing things verbally only leaves us with assumed clarity, and not the actual truth.
The team is beginning to value writing things down before beginning to work on something, and they don’t see it as a time sink anymore. I can’t wait for them to tell me how writing has not just helped them think better, but has also made them happier 🙂
Shankar is thinking 