[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
   

   View Slide

2. Design Doc - What?
   A technical spec about feature or system which includes the
   rationale for each decision made.
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide