Design Doc の書き方 / How to Write a Design Doc (Ja ver.)

「Design doc とは何か」・「何を書けばよいのか」を説明するスライドです。

関連するプレゼンテーション「読みやすいコードの書き方」: https://gist.github.com/munetoshi/65a1b563fb2c271f328c121a4ac63571

© 2023 Munetoshi Ishikawa, supported by LINE corporation

Transcript

1. Munetoshi Ishikawa Design Doc ͷॻ͖ํ
2. ͜ͷηογϣϯͷ஫ҙ఺ Design doc ʹ͸༷ʑͳελΠϧ΍ํ๏࿦͕͋Δ - ͜ͷηογϣϯͰ঺հ͢Δ͜ͱ͸ 1 ྫʹա͗ͳ͍ - ΧελϚΠζ͕ඞཁʹͳΔ͔΋ 

3. ιϑτ΢ΣΞ։ൃͰΑ͋͘Δ໰୊ - ࣮૷ऴྃؒࡍʹઃܭ্ͷ໰୊͕ൃ֮
 → ΄΅࠷ॳ͔ΒίʔυΛॻ͖௚͠
 - ݸʑͷϓϧϦΫΤετ͸ LGTM
 → ίʔυશମͱͯͯ͠ҙຯෆ໌ Design doc Λॻ͘͜ͱͰղܾͰ͖Δ͔΋
4. τϐοΫ - Design doc ͷ֓ཁ - Design doc ͷߏ੒ - ӡ༻࣌ͷ஫ҙ఺ - έʔεελσΟ
5. τϐοΫ - Design doc ͷ֓ཁ - Design doc ͷߏ੒ - ӡ༻࣌ͷ஫ҙ఺ - έʔεελσΟ
6. Design doc ͷ֓ཁ - Design doc ͱ͸ - ʮԿΛʯॻ͔͘ - ʮ͍ͭʯॻ͔͘ - ৄࡉઃܭॻͱͷҧ͍
7. Design doc ͷ֓ཁ - Design doc ͱ͸ - ʮԿΛʯॻ͔͘ - ʮ͍ͭʯॻ͔͘ - ৄࡉઃܭॻͱͷҧ͍
8. Design doc ͱ͸ 1/2 ιϑτ΢ΣΞઃܭॻͷҰछ - ʮͲ͏࣮૷͢Δ͔ʯ͕য఺ - ։ൃऀʹΑͬͯॻ͔ΕΔ
9. Design doc ͱ͸ 2/2 ࣮૷Λߦ͏લʹॻ͘υΩϡϝϯτ - ࣮૷લʹઃܭʹ͍ͭͯٞ࿦ - ࣮૷த΋ΞοϓσʔτՄ design doc ࣮૷ “Twemoji” ©Twitter, Inc and other contributors (Licensed under CC-BY 4.0) https://twemoji.twitter.com/
10. Design doc ͷར఺ ੜ࢈ੑɾϓϩδΣΫτͷ੒ޭ཰ͷ޲্ - ϑΟʔυόοΫαΠΫϧͷ୹ظؒԽ - ࣮૷લͷ໰୊఺ͷચ͍ग़͠ - ίετݟੵ΋Γͷώϯτ
11. Design doc ͷ֓ཁ - Design doc ͱ͸ - ʮԿΛʯॻ͔͘ - ʮ͍ͭʯॻ͔͘ - ৄࡉઃܭॻͱͷҧ͍
12. Design doc ͷয఺ ʮͲ͏࣮૷͢Δ͔ʯʹয఺Λ౰ͯΔ - ໰୊఺ͱղܾࡦͷ໌֬Խ - νʔϜϝϯόʔͱͷٞ࿦ - ίϯςΩετʢഎܠ΍ܦҢʣͷه࿥
13. ؔ࿈͢ΔιϦϡʔγϣϯ 1/2 Կɾͳͥ: ࢓༷ɾ໨తͷ໌֬Խ - PRD (Product Requirements Document) ͩΕɾ͍ͭ: λεΫɾϚΠϧετʔϯ؅ཧ - Πγϡʔ؅ཧπʔϧɾϓϩδΣΫτ؅ཧπʔϧ

14. ؔ࿈͢ΔιϦϡʔγϣϯ 2/2 ৽ϝϯόʔ޲͚ࢿྉɾݱঢ়આ໌ - νϡʔτϦΞϧɾελʔτΨΠυɾΞʔΩςΫνϟจॻ
15. Design doc ͷϖʔδ਺ ௕ͯ͘΋े਺ϖʔδఔ౓ - ୹ͯ͘ࡁΉͳΒͦΕʹӽͨ͜͠ͱ͸ͳ͍ - 20 ϖʔδҎ্ͷ৔߹ → λεΫɾϓϩδΣΫτΛ෼ׂ͢Δ
16. Design doc ͷ֓ཁ - Design doc ͱ͸ - ʮԿΛʯॻ͔͘ - ʮ͍ͭʯॻ͔͘ - ৄࡉઃܭॻͱͷҧ͍
17. ͍ͭ design doc Λॻ͘΂͖͔ ʮԿΛ͢Δ͔ʯ͕͋Δఔ౓ܾ·͔ͬͯΒɺ࣮૷Λ։࢝͢Δલ த௕ظతͳϓϩδΣΫτɾλεΫʹ͍ͭͯॻ͘ - υΩϡϝϯτ࡞੒ࣗମ΋Φʔόʔϔου
 = ؆୯ͳ 1 ߦͷόάमਖ਼Ͱ͸ॻ͔ͳ͍
18. ͍ͭ design doc Λॻ͘΂͖͔ (cont.) Design doc Λॻ͘ج४ͷྫ: - 2 िؒҎ্͔͔ΔλεΫ - ෳ਺ͷϦϦʔεʹ·͕ͨΔϓϩδΣΫτ - ଟ਺ͷϞδϡʔϧɾΫϥεʹӨڹ͢Δमਖ਼
19. Design doc ͷ֓ཁ - Design doc ͱ͸ - ʮԿΛʯॻ͔͘ - ʮ͍ͭʯॻ͔͘ - ৄࡉઃܭॻͱͷҧ͍
20. ΢ΥʔλʔϑΥʔϧͱͷൺֱ: ڞ௨఺ τοϓμ΢ϯͳΞϓϩʔν - ࣮૷ͷલʹઃܭ - จॻͷϨϏϡʔɾٞ࿦ design doc ࣮૷ + ϨϏϡʔɾٞ࿦ “Twemoji” ©Twitter, Inc and other contributors (Licensed under CC-BY 4.0) https://twemoji.twitter.com/
21. ࣮૷ͱͷڥք͕ݫ֨Ͱ͸ͳ͍ - ࣮૷୲౰ऀɾνʔϜʹΑͬͯॻ͔ΕΔ - ׬ᘳͳৄࡉ͸ٻΊͳ͍: ੩తݕূͷলུɾ։ൃதͷΞοϓσʔτ - ΞδϟΠϧ։ൃʹ΋ద༻Մೳ ΢ΥʔλʔϑΥʔϧͱͷൺֱ: ૬ҧ఺ design doc ࣮૷ ୲౰ऀ “Twemoji” ©Twitter, Inc and other contributors (Licensed under CC-BY 4.0) https://twemoji.twitter.com/
22. Design doc ͷ֓ཁ: ·ͱΊ - Design doc ͸ιϑτ΢ΣΞઃܭॻͷҰछ - ʮͲ͏ʯ࣮૷͢Δ͔ʹয఺Λ͋ͯΔ - தɾେن໛ͳ࣮૷Λ࢝ΊΔલʹॻ͘ - ࣮૷தʹߋ৽͠ಘΔ
23. τϐοΫ - Design doc ͷ֓ཁ - Design doc ͷߏ੒ - ӡ༻࣌ͷ஫ҙ఺ - έʔεελσΟ
24. Design doc ͷϑΥʔϚοτ ߲໨ʹରͯ͠ʮݫີͳʯϑΥʔϚοτ͸ͳ͍͜ͱ͕ଟ͍ - ඞཁे෼ͳ߲໨ͰηΫγϣϯΛߏ੒͢Δ - ʮϑΥʔϚοτΛຒΊΔ͜ͱʯΛ໨తԽ͠ͳ͍
25. యܕతͳ design doc ͷߏ੒ - ໨తɾΰʔϧʢ΄΅ඞਢʣ - എܠ - ઃܭͷ֓ཁ - ৄࡉઃܭ - ͦͷଞͷؔ৺ࣄ τοϓμ΢ϯʹཧղͰ͖Δߏ੒ʹ͢Δ
26. యܕతͳ design doc ͷߏ੒ - ໨తɾΰʔϧʢ΄΅ඞਢʣ - എܠ - ઃܭͷ֓ཁ - ৄࡉઃܭ - ͦͷଞͷؔ৺ࣄ
27. ໨తɾΰʔϧ ਺จͰʮԿΛ࣮ݱ͢Δͷ͔ʯΛఆٛ͢Δ - ʮ…ػೳΛ࣮૷͢ΔͨΊͷɺσʔλετΞͱͦͷϞσϧΛ࣮૷͢Δʯ - ʮ…ΛϓϩμΫτ಺Ͱར༻Մೳʹ͢ΔϥΠϒϥϦΛ࡞੒͢Δʯ - ʮ…ΛϦϑΝΫλ͠ɺ…ͷػೳ௥ՃΛ༰қʹ͢Δʯ
28. ໨తɾΰʔϧ: ஫ҙ఺ ௕͘ॻ͖͗͢ͳ͍ - ඞཁͳΒ͹ PRD Λผ్༻ҙ - ʮ࣮૷͢ΔՁ஋͕͋Δ͔ʯ΋جຊతʹ͸ PRD Ͱٞ࿦ είʔϓΛ໌֬ʹ͢Δ - ඞཁʹԠͯ͡ʮout of scopeʯ΍ʮࠓޙͷ༧ఆʯΛ໌ه
29. యܕతͳ design doc ͷߏ੒ - ໨తɾΰʔϧʢ΄΅ඞਢʣ - എܠ - ઃܭͷ֓ཁ - ৄࡉઃܭ - ͦͷଞͷؔ৺ࣄ
30. എܠ ਺ஈམҎ಺Ͱ࣮૷͢Δཧ༝ɾલఏ஌ࣝɾ੍໿Λઆ໌ - ͜ͷ࣮૷ɾϦϑΝΫλϦϯά͕ඞཁͳཧ༝ɾར఺ - ༻ޠɾٕज़తഎܠ - ༏ઌ͢΂͖߲໨: ֦ுੑɾؤ݈ੑɾੑೳ…
31. എܠ: ஫ҙ఺ ௕͘ॻ͖͗͢ͳ͍ - ؔ࿈จॻʢPRDɾଞͷ design docʣ౳ͷϦϯΫΛར༻ ໨తɾΰʔϧͷޙʹॻ͘ - ʮԿʹ͍ͭͯ࿩͍ͯ͠Δ͔ʯΛઌʹཧղͤ͞Δ
32. എܠ: ஫ҙ఺ (cont.) ૝ఆಡऀΛҙࣝ͢Δ - ͦͷػೳɾϓϩμΫτʹؔΘ͍ͬͯͳ͍ਓ΋ର৅͔ ͦͷػೳͷ։ൃऀ ͦͷϓϩμΫτͷ։ൃऀ ಉ͡୲౰ྖҬ৬छͷ։ൃऀ “Twemoji” ©Twitter, Inc and other contributors (Licensed under CC-BY 4.0) https://twemoji.twitter.com/
33. యܕతͳ design doc ͷߏ੒ - ໨తɾΰʔϧʢ΄΅ඞਢʣ - എܠ - ઃܭͷ֓ཁ - ৄࡉઃܭ - ͦͷଞͷؔ৺ࣄ
34. ઃܭͷ֓ཁ ઃܭͷॏཁͳ෦෼ʹ͍ͭͯॻ͘ɾඳ͘ - ࣮૷ͷجຊతͳΞΠσΟΞ - ؆ུԽͨ͠ΫϥεਤɾϞδϡʔϧߏ੒ਤ - ॏཁͳཁૉͷྻڍͱઆ໌
35. ઃܭͷ֓ཁ: جຊతͳΞΠσΟΞ ࣮૷ࠔ೉ͳ఺ɾؾΛ͚ͭΔ΂͖఺ͷղܾ๏Λࣔ͢ - ʮ…͕ະ஌Ͱ͋ΔͨΊɺαΠζՄมͳ LRU ΩϟογϡΛ࢖͏ʯ - ʮ…ͷ॥؀ґଘͷղܾʹ SeviceLocator Λ࢖͏ʯ - ʮ…ͷಠཱੑͷ֬อͷͨΊʹ Layer A ͱ B Λ෼཭͢Δʯ
36. ઃܭͷ֓ཁ: ؆ུԽͨ͠Ϋϥεਤ ॏཁͳΫϥεɾϞδϡʔϧͱͦͷؔ܎ੑΛࣔ͢ - खඳ͖ɾ؆ུԽͨ͠ϑΥʔϚοτ΋Մ
37. ઃܭͷ֓ཁ: ஫ҙ఺ ࡉ͔͘ॻ͖͗͢ͳ͍ - ॏཁͰͳ͍ཁૉΛؒҾ͘ - ಛʹ஫ҙ͢Δ΂͖͜ͱʹয఺Λ౰ͯΔ ؆ུԽ
38. యܕతͳ design doc ͷߏ੒ - ໨తɾΰʔϧʢ΄΅ඞਢʣ - എܠ - ઃܭͷ֓ཁ - ৄࡉઃܭ - ͦͷଞͷؔ৺ࣄ
39. ৄࡉઃܭ ʮઃܭͷ֓ཁʯΛΑΓৄࡉʹॻ͘ɾඳ͘ ཁૉ͝ͱɾݟΔ֯౓͝ͱʹηΫγϣϯΛ࡞Δ - ཁૉ͝ͱ: ϞδϡʔϧɾΫϥεɾίϯϙʔωϯτɾϨΠϠ - ݟΔ֯౓͝ͱ: ঢ়گ΍৚݅ɾλΠϜϥΠϯɾAPI
40. ৄࡉઃܭ: ߲໨ྫ - Ϟδϡʔϧ͝ͱͷ֓ཁઆ໌ɾΫϥεਤ - ϞσϧΫϥεɾσʔλߏ଄ͷҰཡ - API ͷϦετɾ࢖༻ྫͷίʔυ - యܕతͳσʔλϑϩʔɾγʔΫΤϯεਤ - ٖࣅίʔυ
41. యܕతͳ design doc ͷߏ੒ - ໨తɾΰʔϧʢ΄΅ඞਢʣ - എܠ - ઃܭͷ֓ཁ - ৄࡉઃܭ - ͦͷଞͷؔ৺ࣄ
42. ͦͷଞͷؔ৺ࣄ ϓϩδΣΫτͷਐΊํɾӨڹൣғɾ஫ҙ఺౳ʹؔ͢Δิ଍
43. ͦͷଞͷؔ৺ࣄ ϓϩδΣΫτͷਐΊํɾӨڹൣғɾ஫ҙ఺౳ʹؔ͢Δิ଍ - ୲౰ऀ - େ·͔ͳλεΫͷखॱ - ϦϦʔεɾϞχλϦϯάϓϥϯ
44. ͦͷଞͷؔ৺ࣄ ϓϩδΣΫτͷਐΊํɾӨڹൣғɾ஫ҙ఺౳ʹؔ͢Δิ଍ - ະղܾͷ໰୊ɾ੍ݶ - ଞʹӨڹΛड͚ΔϞδϡʔϧ - ηΩϡϦςΟɾϓϥΠόγʔɾύϑΥʔϚϯε
45. యܕతͳ design doc ͷߏ੒ - ໨తɾΰʔϧʢ΄΅ඞਢʣ - എܠ - ઃܭͷ֓ཁ - ৄࡉઃܭ - ͦͷଞͷؔ৺ࣄ
46. Design doc ͷߏ੒: ·ͱΊ ඞཁे෼ͳ߲໨Ͱߏ੒͢Δ - ʮ໨తɾΰʔϧʯ͸΄΅ඞਢ - ֎෦ͷυΩϡϝϯτͳͲ΋ར༻ τοϓμ΢ϯʹཧղͰ͖Δߏ੒ʹ͢Δ - ໨త → എܠ - ઃܭͷ֓ཁ → ৄࡉઃܭ
47. τϐοΫ - Design doc ͷ֓ཁ - Design doc ͷߏ੒ - ӡ༻࣌ͷ஫ҙ఺ - έʔεελσΟ
48. Ξϯνύλʔϯ 1 1. ʮ׬ᘳͳʯ design doc Λॻ্͖͛Δ 2. ϨϏϡʔͷϛʔςΟϯάʹ 10 ਓҎ্ট଴ 3. ٞ࿦தʹઃܭͷ໰୊͕ൃ֮ 4. ࠷ॳ͔Β design doc Λॻ͖௚͢
49. ٞ࿦ͷλΠϛϯά ٞ࿦ͱ design doc ࡞੒Λަޓʹߦ͏ ࠷ॳͷٞ࿦͸… - ʮগਓ਺Ͱʯ: ςοΫϦʔυͱͷ 1-on-1 ͔Β࢝Ίͯ΋Α͍ - ʮղܾҊ͕ͳͯ͘΋ʯ: ٞ࿦ͰղܾҊΛݟ͚ͭΕ͹Α͍ - ʮ΄΅നࢴͰ΋ʯ: ٞࣄ࿥తʹ design doc Λॻ͘͜ͱ͕Ͱ͖Δ
50. Ξϯνύλʔϯ 2 1. Design doc ͷ࡞੒ɾϨϏϡʔ͕׬ྃ 2. ࣮૷Λ։࢝ 3. ࣮૷தʹઃܭͷ໰୊͕ൃ֮ 4. ઃܭΛมߋ͠ͳ͍Α͏ʹ ͦͷ৔͠ͷ͗ͷղܾࡦΛ࠾༻
51. Design doc ߋ৽ͷλΠϛϯά ࣮૷தʹ΋ઃܭΛมߋͯ͠΋Α͍ ୹͍αΠΫϧͰʮͲ͏ղܾ͢Δ͔ʯΛٞ࿦͢Δ - ඞཁͳΒ͹ design doc Λߋ৽͢Δ
52. Ξϯνύλʔϯ 3 1. ઃܭมߋͷ౓ʹ design doc Λߋ৽ 2. ʮελʔτΞοϓΨΠυʯͱ͠΋࠶ར༻ 3. ଟେͳίετ͕ඞཁʹͳΔ - ৽نϝϯόʔ͸େྔͷ design doc ΛಡΉඞཁ͕͋Δ - ܰඍͳมߋͰ΋େྔͷ design doc ͷߋ৽͕ඞཁʹͳΔ
53. Design doc ͷ੹೚ൣғ Design doc ͸جຊతʹ͸࢖͍ࣺͯ - 1 ϓϩδΣΫτͰ 1 design doc - ΞʔΧΠϒ΍ʮܦҢΛ஌Δख͕͔Γʯʹ͸ͳΔ - ଞͷબ୒ࢶΛߟྀ: ΞʔΩςΫνϟจॻɾPRDɾνϡʔτϦΞϧ
54. Ξϯνύλʔϯ 4 1. ػೳ։ൃͷϓϩδΣΫτ͕׬ྃ 2. …਺Χ݄ޙ… 3. ػೳ௥ՃͷϓϩδΣΫτ͕ൃ଍ 4. Ҏલͷ design doc ͕୳ͤͳ͍
55. Design doc ͷτϨʔαϏϦςΟ Design doc ͷϦϯΫΛ׆༻ - ϓϧϦΫΤετ͔ΒࢀরՄೳʹ - Πγϡʔνέοτ͔ΒࢀরՄೳʹ Design doc ͷϦετΛ࡞Δ - ख࡞ۀͰ؅ཧ͢ΔΑΓ΋࢓૊ΈͰ؅ཧ
56. ӡ༻࣌ͷ஫ҙ఺: ·ͱΊ - ٞ࿦ɾϨϏϡʔͷαΠΫϧ͸୹Ίʹ - ࣮૷தʹ΋ design doc ͸ߋ৽Մ - Design doc ʹʮଞͷ໾ׂʯΛ௥Ճ͠ͳ͍ - ޙ͔Β design doc ΛࢀরͰ͖ΔΑ͏ʹ
57. τϐοΫ - Design doc ͷ֓ཁ - Design doc ͷߏ੒ - ӡ༻࣌ͷ஫ҙ఺ - έʔεελσΟ
58. έʔεελσΟ ʮઃఆը໘ʯͷϦϑΝΫλϦϯάͷґཔ ௨஌ ը࣭ઃఆ Ξχϝʔγϣϯ << Φϯ >> << ߴը࣭ >> << ϑϧ >>
59. ґཔ࣌ͷϛʔςΟϯά ґཔΛड͚Δ࣌఺Ͱ໨త΍എܠΛ໌֬ʹ͢Δ
60. ϦϑΝΫλϦϯάର৅ͷௐࠪ ݱࡏͷঢ়ଶΛ೺Ѳɾ໰୊఺ͷચ͍ग़͠
61. ϦϑΝΫλϦϯάର৅ͷௐࠪ (cont.) ݱࡏͷঢ়ଶΛ೺Ѳɾ໰୊఺ͷચ͍ग़͠ - ໨తɾഎܠΛ۩ମԽ͢Δ
62. ઃܭํ਑ͷٞ࿦ ςοΫϦʔυͱͷ 1-on-1 ͳͲͰઃܭҊΛٞ࿦͢Δ
63. ௥Ճɾߋ৽ඞཁͳ߲໨ 1/2 ໨తɾഎܠ - ઃܭҊΛݩʹ۩ମԽ λεΫϓϥϯ - ͲͷॱͰ࣮૷͢Δ͔ - ϦϑΝΫλϦϯάதʹ௥Ճ͞Ε߲ͨ໨ͷऔΓѻ͍
64. ௥Ճɾߋ৽ඞཁͳ߲໨ 2/2 ςετ - ϢχοτςετͰݕূ͢Δ಺༰ - ϦάϨογϣϯςετͷํ๏ ߲໨௥Ճ࣌ͷखॱ - αϯϓϧίʔυ
65. έʔεελσΟ: ·ͱΊ ٞ࿦ͷ͍ͭͰʹॻ͘ͱָ
66. ·ͱΊ Design doc: ιϑτ΢ΣΞઃܭॻͷҰछ - υΩϡϝϯτͷ੹೚ൣғΛ໌֬ʹ - ඞཁͳ߲໨Λඞཁͳ͚ͩॻ͘ - ୹͍αΠΫϧ͕ॏཁ
67. Appendix 1: πʔϧ ڞಉฤूɾཤྺɾίϝϯτ΍ϨϏϡʔ͕Ͱ͖Ε͹ԿͰ΋ྑ͍ - Atlassian confluence, Notion - GitHub Gist, markdown in repository - Google docs, Dropbox Paper, Box notes
68. Appendix 2: Design doc ͷྫ Chromium design docs - https://www.chromium.org/developers/design-documents Bazel design docs - https://github.com/bazelbuild/proposals