What Engineering office actually is
- #Advent Calendar
- #engineering management
- #Engineering Office
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.
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.
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.
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.
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.
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.
Later down the road, you might consider using the design document as groundwork for more permanent team documentation, such as a Tech Wiki.
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!