Write it down
This article is inspired by tanya reilly’s continous talk slides, where it contains a lot of wisdom: “Taking the time to deliberately choose what we work on, write things down, make a safe supportive environment for other people, and finish things and put them away.”
Why write it down?
To preserve information, to own and share the knowledge, and most importantly, to communicate so that it is easier for the team to collaborate and scale.
Just three years back, when I thought about writing it down, as the Chinese saying goes “The palest ink is better than the best memory”, I considered it more as a good personal habit to preserve information. As a software engineer who wrote code every day, I believed that code and tests are the live documentation. I was largely influenced by Uncle Bob’s Clean Code, and treated commenting in the code as a code smell rather than necessary: If code is written in a self-explanatory way, we don’t need to write comments to explain, which gets out-of-date quickly anyway. Thus I didn’t find myself writing down much except code.
Two years back, I had the realization that I want to own my expertise and get feedback on how I can improve. One way to achieve this goal is to share what I know by writing it down. This is a mind-shifting exercise for me. It not only gives me the opportunity to practice organizing my thoughts and writing to explain it but also helps me record and reflect. Writing a blog post alone completes a short feedback cycle for me to re-learn what I know, explain from one perspective, accept things that I still don’t know, and spark some new seeds in thoughts for the next time.
Last year, when I was preparing my talk on how to write a better story in code, in addition to writing self-explanatory code in the language of the domain(ubiquitous language), I included a slide talking about using other communication artifacts to complement code, examples include declarative gherkin scenarios that describe business workflows, unit tests to demonstrate different edge cases of the functionality, pull request descriptions with why the feature is needed, what changes are included, testing notes and areas needs more careful review for reviewers, commit messages for each small code change, coding decisions on why we need to add assertion here or catch exception there, and more documentation and necessary comments in code please. After all, along with the code, these are all media to make sure effective communication happens.
What to write down?
Write it down to record communication happened and to facilitate communication happening.
Two months ago, I took a new role as an Engineering Manager and started to grow a small product team from 1 engineer to 3 engineers and 1 tester. For the past three weeks, I have found myself desperately advocating “write it down” all the time, and now I believe that “Writing is one of the most underrated career skills.”
The first “write it down” moment that came to me is to add more context in pull request descriptions. This is easy to identify and fix by enforcing GitHub pull request template. This small change serves a reminder for engineers to include the background information, change logs and testing notes upon opening a pull request. As our team practices pair programming, most of the time the changes in the pull request are already known by engineers and tester, it doesn’t seem adding too much value to improve current communication, but it helps to record for future references, and easier for us to rationale why we made this change back then.
The second “write it down” moment I find lacking is to write design documents for large user stories, as in the agile development setting.
I went to LeadDevConf this year(please checkout again Tanya’s conference report, which shows me the concrete example of “what to write down” in regards of conference report), and learned “Lightweight architecture decision records(ADRs)”. It resonated with me because working with code running in production for years, we find ourselves asking so many times “Why did we decide to do it this way?”, and find nothing to rationale after digging into the git history for a while.
“We need to make it as easy as possible to socialize decisions and record why we made them. Michael Nygard introduced the idea of Architectural Decision Records, a structure for recording the context around decisions. David recommends we write them in markdown, have them reviewed just like code, and keep them together in a folder in the codebase, where they’ll be easy to find. Have a separate repo for big decisions that span multiple projects.”
Please find more details here, https://github.com/davidaayers/comm-and-doc-arch-decisions with references to real-world examples of ADRs.
In my mind, this applies to smaller scale coding decisions, modeling discussions, that may or may not impact the application’s overall “architecture”. Start with a google doc in the team drive, write down plans to tackle the large story, make sense of what requirements are, provide different options to solve, this “writing it down” alone refines our plan, helps decision-making, and gives us better context on how to decompose story implementations, and make trade-off decisions explicit.
The next “write it down” moment is to how to write JIRA tasks/stories to be ready before the grooming meeting. These story descriptions serve as communication backbone among the scrum team among engineering and product and testing and technical communication department, etc. The quality of the story writing directly impacts the effectiveness we could have during the grooming session.
With some google search using “definition of ready” and “INVEST criteria”, this is by far what I have got I like best:
Having a Definition of Ready means that stories must be immediately actionable. The Team must be able to determine what needs to be done and the amount of work required to complete the User Story or PBI. The Team must understand the “done” criteria and what tests will be performed to demonstrate that the story is complete. “Ready” stories should be clear, concise, and most importantly, actionable.
I also like this definition of ready from http://scrumbook.org/, where contains a lot of resources on how to practice scrum(Thanks to Chris who points me to this site).
With guidelines from the above definition of ready, most importantly, actionable to any engineer on the team(new or veteran), it forces us to think with more details and write down the assumptions of the knowledge that we need to know about the system, instead of keeping them in each other’s head.
What are your “write it down” moments?
