[DevDojo] Design Doc

In this course, we will explain the basic knowledge of Design Doc for product development and introduce the template that Mercari actually uses now. We will also cover how to write a good design doc and deal with it in Mercari.

Transcript

1. Design Doc Fall 2022 Dev Dojo @hide
2. Design Doc - What? A technical spec about feature or system which includes the rationale for each decision made.
3. Design Doc - Why? • Transfer knowledge • Improve quality by getting feedback • Other teammates can use their experience to help point out potential errors before they happen • Clarify your thoughts about a design by writing them down to make them more real and feasible than having them in your head • Improve code review quality • Get alignment with architecture and other technical detail
4. Design Doc - When? Spec Discussion Design doc Development PM plans to think of new idea Design and functionallity are fixed Start development after getting approval for design doc
5. Design Doc - Process Design Discussion Review Code Before writing code,and/or while prototyping By people having an insight for the domain Incorporate insight and idea Similar to “develop/review code” but It costs much less if written before actual code
6. Design Doc - Lifespan • Design Docs are a historical document ◦ Understand why decisions were made in the past ◦ Don't update them ◦ They are not documentation ◦ For changes, write a new design doc ▪ Maybe link to it from the old one • Non-historical document ◦ e.g. confluence, onboarding wiki
7. Design Doc - How? • Follow the templates to start ◦ An Example Template ◦ Some teams have their own template • Put it in Team Drive ◦ #group-design-doc • Get feedbacks by review ◦ Guideline for reviews
8. Design Doc - Teams • Each team may have a different process ◦ Design Docs may be required before implementation of some features ◦ Other engineers or the tech lead may need to approve ◦ Templates might be different ◦ Some teams may not have a design doc flow • Individual ◦ Even if you team does not require it, you might write design docs for your own learning