The first day’s post of Mercari Advent Calendar 2020 is brought to you by Ann Kilzer from the Mercari Web Platform team.
As developers, we’re known for writing code, but often, there is a lot of planning and preparation to ensure we write the right code. Design Documents are a helpful tool in this planning.
When should I write a design document?
Design documents are best for projects of significant complexity. As a rule of thumb, I would write a design document for any piece of work that will span about one month (multiple sprints, if you’re using agile), requires a division of labor, crosses team boundaries, or requires a group decision.
It’s usually not worth it to write a design document for small pieces of work where the direction is clear, such as bug fixes or minor additions.
Know your audiences
Who are we writing for? The first audience that comes to mind is the people doing the work. A design document helps everyone figure out what will be done and how.
Next is the stakeholders. The new feature will likely impact other people at your company. Make sure to gather their input to meet expectations.
Next is future you. You might return to this document later, having forgotten some of the details. Leaving good information, not only on the initial plan, but on how the plans change, and what decisions are made, will help you down the road.
Lastly, design documents become the groundwork for future documentation. They will be read by your future teammates, who will be reading them to understand how the tool works. These people may be recent hires who weren’t around when your design was implemented.
Be specific and clear
The comedian and writer John Hodgman says “Specificity is the soul of narrative.” Though technical documentation is not prose, the same advice can help us write with clarity.
I’ve occasionally seen design documents with goals like this:
Project: Kabigon
Goals:
- Make the best experience for our customers
- Enable faster developer productivity
These are wonderful goals, but are they specific? And with a tendency to use code names for projects (i.e. Kabigon, context is unclear. A newcomer to this team wouldn’t learn much.
A better set of goals might look like:
Project: Kabigon
Goals:
- Build a batch pipeline for processing marketplace images
- Scale each image to the appropriate size, filter for invalid products, autogenerate tags
- Latency: Images should be processed within 30 minutes of entering the pipelines
(Note this example and metrics are invented for the purpose of demonstration and do not reflect how Mercari’s software works.)
Now a reader has an idea what Kabigon is all about. And if we want to keep the original goals, it would be useful to add them as side goals.
A similar goal to specificity is clarity. Be sure to document TLAs (three letter acronyms) or any company jargon. This makes your document friendlier to a wider audience.
Structure
While teams at Mercari vary in how they create Design Documents, here’s my suggested structure for design documents (You can also see the production readiness checklist template here to get another perspective). Note that this isn’t meant to be a guideline, rather, ideas to build upon. Therefore, developers should feel free to adapt as necessary to promote creativity.
Design Document Template
Project Name
People responsible for the work
Overview
- Remember to be specific 😃
- Share the business perspective and motivations
Related tickets
User Stories
- As a [specific type of user], I want to [goal based task]
- Really try to get in the mind of your users. Avoid developer “tunnel vision” where you focus on implementation over motivation
- Bad: “As a shopper, I want to complete a reCaptcha when logging in.”
- Better: “As a shopper, I want to log in securely”
- Even better: “As a shopper, I want to keep personal information such as past purchases, payment details, and likes secure.”
Research
- Related articles and knowledge from the wider tech community
- Helpful to provide both links and a high-level summary
MVP Goals
- Make it clear what work needs to get done, and what can be saved for later. Making a clear MVP will help your feature reach your customer and not get stuck in development purgatory
- One useful format: MoSCoW (Thanks to a former colleague for teaching me this framework).
- Must
- Should
- Could: Useful for discussing alternatives
- Won’t: This is important to define to avoid scope creep
Diagrams
- Architecture
- Information flow
- Draw.io is a useful tool.
- Diagrams can be useful to propose alternatives
Security and Privacy Considerations
Open Questions
- Great for the driving further discussion when you have a meeting
- Be sure to record decisions and answers in the document
Remember design documents are a living document. It’s great to gather feedback in several rounds, and update the documentation as new decisions are made, or information presented.
Review Process:
- Make a first draft and send it out to your team and stakeholders. Google Docs is a useful tool as it allows commenting and collaborative editing.
- Schedule a meeting for all interested stakeholders (be sure to invite cross-team experts) for one hour.
- Address any open comments or questions
- Make sure everyone’s in agreement
- Make appropriate updates to the document after the meeting
- Start the work, and update the document as necessary to optimize asynchronous communication.
Later down the road, you might consider using the design document as groundwork for more permanent team documentation, such as a Tech Wiki.
Conclusion
Engineering is so much more than writing code, and improved technical communication keeps us in sync when working remotely. Thanks for reading my thoughts on design documents, and I hope it helps you collaborate better with your teammates.
Mercari is looking for software engineers who share our mission and values.
https://careers.mercari.com/job-categories/engineering/
Tomorrow’s blog post —the second in the Mercari Advent Calendar 2020— will be written by Chica Matsueda. Hope you are looking forward to it!
