BA (16/52): How to get engineers to write design docs
At Apple, we rarely wrote engineering design docs.
This meant often times the reasoning behind decisions were difficult to recall, difficult to detangle tech debt, and onboarding was a tribal process.
At Google, every conversation ended with “I will write a doc on that.”
This meant you had no idea what document was relevant or important to the discussion. Mostly, these were artifacts people submitted for promotion committees.
At Nike, all we ever did was write design docs and make slide decks.
When you spend so much time perfecting the doc instead of spending time coding well, there is a favorite saying I hear from engineers all the time - “code ships products, not docs”.
Getting engineers to write design docs is hard. Why?
Documentation processes are often overbearing or too arduous.
Process tends to focus more on documentation completion rather than content.
Process creators often run a bit too far with complicated long design doc templates.
Design docs often invoke top down, command control approval feelings.
So, how do you build documentation processes that engineers will be happy to abide by?
Before talking about that, a note on why teams or organizations write documentation:
Design docs tell the history of an organization as it evolves. As organizations scale, new members join, it is important they understand how the software they will work on has evolved include what platforms, decisions, technologies were used when and why. This gives them context as they chart the future evolution of the codebase and add their own verse to the narrative.
Design docs are important for robust and effective remote or async engineering teams. At Apple, we didn’t write docs because there was a heavy culture of working face to face, engineering conversations that immediately let to code which led to demo. It did have a side effect that onboarding was a tribal process. Institution knowledge was tribal and required you spending time learning from others. Technical debt caused surprises in unexpected moments. This doesn’t scale when you are remote.
Design docs represent a decision point in time. Whether we pick one auth implementation over another, which design pattern we went with and why, why build these specific microservices; decisions drive the product forward. Often times, decisions turn out to be the wrong bet. Design docs can help us trace our steps back and see the motivations that led to the decisions so they can be discussed again.
Design docs are tools for conversations more so than decision making. To prevent top-down, command and control processes which can bog down progress, the best way to make decisions is to empower everyone to make architectural decisions.
What makes for great design documentation process?
Keep it focused.
What are you trying to do?
Why do you want to do it?
What is involved to achieve the desired outcome? If you don’t know the work to be done - spike it.
Keep the template short.
Give the basic structure outlined above. Let the author add headings or content as needed.
Keep it open and indexed.
Once the document is ready - share it with everyone in the organization.
Have a central record of every doc written including date of creation, and doc state (Drafting, In Review, Approved, Implemented etc). Andrew Harmel-Law recommends also marking design docs as Obsolete if they have been superseded or no longer in the codebase. This is a great way to keep dead code out from the main code base.
Keep it decentralized.
Instead of approvals, allow author to identify the team members who could veto the approach. This usually means teams most impacted by the proposed get a bigger say than most.
Conversation above approval
Andrew Harmel-Law in his great article Scaling the Practice of Architecture, Conversationally outlines that design docs should be conversations rather than approval seeking. It is about soliciting feedback and developing better well rounded outcomes rather than seeking approvals.
Finding dedicated time for a group/architecture council to come together regularly and discuss design docs that need to be reviewed is extremely helpful. However, the goal of the council is not to make a decision but to have a conversation on the outlined proposal. Most architecture councils I have seen fail because of approval seeking end goals.
Not everything has to be a document.
This is perhaps the most important and most difficult hallmark of a good documentation process - when something doesn’t need to be documented. My rule: if it can be covered under a week, no documentation needed. Beyond that, use your own discretion.
Until next time 👋!
-Aadil
What did you think about this week’s newsletter?