How to Write a Design Doc (En ver.)

A slide deck explaining what a design doc is and what to write in it.

Related presentation series, "Code Readability": https://gist.github.com/munetoshi/65a1b563fb2c271f328c121a4ac63571

© 2023 Munetoshi Ishikawa, supported by LINE corporation

Transcript

1. Munetoshi Ishikawa How to Write a Design Doc
2. Note for this session Many different styles and methodologies for design docs - This session introduces only one of them - Customize if you need to 

3. Common problems in software development A critical design problem is found during implementation
 → Re-implement almost from scratch Each pull-request looks good
 → The codebase itself gets hard to read These problems can be solved though design docs
4. Topics - Introduction - Contents of design doc - Anti-patterns - Case study
5. Topics - Introduction - Contents of design doc - Anti-patterns - Case study
6. Introduction - What a design doc is - What to write - When to write - Comparison with waterfall
7. Introduction - What a design doc is - What to write - When to write - Comparison with waterfall
8. What a design doc is 1/2 Document for software design - Focuses on how to solve - Written by developers
9. What a design doc is 2/2 Document written before implementation - To discuss about design before implementation - May be updated even during implementation design doc implementation “Twemoji” ©Twitter, Inc and other contributors (Licensed under CC-BY 4.0) https://twemoji.twitter.com/
10. Advantages of a design doc Improves a project's productivity and success rate - Short feedback iteration - Problem-checking in advance - Clue of man-hour estimation
11. Introduction - What a design doc is - What to write - When to write - Comparison with waterfall
12. Main purpose Focuses on “how to implement” - Clarification problem and solution - Discussion with team members - Record as background of the implementation
13. Related documents What/Why: Specification/requirement statement - PRD (Product Requirements Document) Who/When: Task planning or milestone - Issue/project management tool Instruction/Catching-up - Tutorials, getting started guide
14. Number of pages A few pages to a dozen pages - Short is preferred - Split a task/project if the document becomes too long
15. Introduction - What a design doc is - What to write - When to write - Comparison with waterfall
16. When to write After deciding what to do roughly, before implementation For a middle/long project or task - Documentation is an overhead
 = Not required for an easy one-line bug fix
17. When to write (cont.) Example of standard to write a design doc: - Taking 2 or more weeks - Requiring multiple release periods - Involving many modules/classes
18. Introduction - What a design doc is - What to write - When to write - Comparison with waterfall
19. Comparison with waterfall: Same points Top-down approach - Design first, implement later - Has review design doc + review and discussion “Twemoji” ©Twitter, Inc and other contributors (Licensed under CC-BY 4.0) https://twemoji.twitter.com/ implementation
20. Flexibility between implementation and design - Written by the implementer/team - May update while developing - Adaptive with agile software development Comparison with waterfall: Different points design doc implementation implementer “Twemoji” ©Twitter, Inc and other contributors (Licensed under CC-BY 4.0) https://twemoji.twitter.com/
21. Introduction: Summary Document for software design - Focusing on “how to solve” - For large/middle task - Updatable during implementation
22. Topics - Introduction - Contents of design doc - Anti-patterns - Case study
23. Format of design docs No concrete format, basically - Comprising of necessary and sufficient sections - “Fill in the format” is not the objective
24. Typical design doc contents - Objective/goal (required for most cases) - Background - Design overview - Design details - Concerns Section order: top-down approach
25. Typical design doc contents - Objective/goal (required for most cases) - Background - Design overview - Design details - Concerns
26. Objective/goal Explain “what to realize” in a few sentences - “FOO achieves…” - “BAR is a new API to replace…” - “This refactoring is to simplify…”
27. Objective/goal: Note Do not write too much - Prepare a separate document (PRD) if required - Use PRD to discuss whether it is worth implementing Make the scope clear - Create sections of “out-of-scope” or “future plan” if required
28. Typical design doc contents - Objective/goal (required for most cases) - Background - Design overview - Design details - Concerns
29. Background Explain context and reasons in a few paragraph - Reasons for and benefits of the implementation/refactoring - Terminology and technical background - Prioritization: Scalability, robustness, performance…
30. Background: Note Do not write too much - Use links to related documents (PRDs, other design docs, etc.) Write after the objective/goal section - Make them understand “what we're talking about” first
31. Background: Note (cont.) Define intended readers - People who are (not) related with the feature/product developers of the feature developers of the product developers in the same role “Twemoji” ©Twitter, Inc and other contributors (Licensed under CC-BY 4.0) https://twemoji.twitter.com/
32. Typical design doc contents - Objective/goal (required for most cases) - Background - Design overview - Design details - Concerns
33. Design overview Write/draw only important points - Basic ideas for the implementation - Simplified class/module diagrams - List of important entities and descriptions
34. Design overview: Basic idea Briefly explain solutions for the most important issue - “We use LRU with adaptive size for dynamic demand…” - “Backward dynamic references are resolved by SeviceLocator” - “Here, layer A is split from B to minimize…"
35. Design overview: Simplified diagrams Explain important classes and relationships - Hand-drawn diagrams are acceptable
36. Design overview: Note Do not write/draw too much details - Focuses only on important elements - Omit unimportant elements simplify
37. Typical design doc contents - Objective/goal (required for most cases) - Background - Design overview - Design details - Concerns
38. Design details Same as design overview, but detailed Create a sub-section for each element and aspect - Element: module, class, component, layer - Aspect: condition, timeline, API
39. Design details: Example of sub-sections - Description for each module, class diagram - List of model classes - List of APIs and usage examples - Typical data flow and sequence diagram - Pseudo code
40. Typical design doc contents - Objective/goal (required for most cases) - Background - Design overview - Design details - Concerns
41. Concerns Task management, affected features, and other concerns
42. Concerns Task management, affected features, and other concerns - Contact points - Rough task ordering - Plan of release and monitoring
43. Concerns Task management, affected features, and other concerns - Known issues and limitations - Affected modules - Security, privacy, performance
44. Typical design doc contents - Objective/goal (required for most cases) - Background - Design overview - Design details - Concerns
45. Contents of a design doc: Summary Comprises of necessary and sufficient sections - Section of objective/goal is almost required - Use external document if possible Top-down approach - Objective → background - Design overview → details
46. Topics - Introduction - Contents of design doc - Anti-patterns - Case study
47. Anti-pattern 1 1. Finish writing a “perfect” design doc 2. Invites 10+ members for the review 3. A fundamental defect found 4. Rewrite the whole document
48. When to discuss Iterate discussion and writing Fine to start with… - A small group: e.g., only with a tech-lead - No concrete idea: Find it during the discussion - Almost blank document: Minutes can be a good draft
49. Anti-pattern 2 1. Finish design doc review 2. Start implementation 3. A structural problem found 4. Workaround with ad-hoc patch
50. When to update Modify the design even during implementation Discuss “how to solve” in a short cycle - Revise the design doc if required
51. Anti-pattern 3 1. Revise a design doc for each design change 2. Reuse design docs as “tutorial documents” 3. Spend a lot of time to… - Read many large docs to get started - Revise many existing docs
52. Responsibility of design doc A design doc is disposable, basically - One project/task, one design doc - May be used as archives, clue to know the history - Other options: PRD, tutorials, …
53. Anti-pattern 4 1. Finish a project successfully 2. …several months later… 3. Update the feature specification 4. Hard to search the previous design doc
54. Traceability of a design doc Keep the design doc link - As a pull-request description - As an issue ticket description/comment Maintain a list of design docs - By a system rather than by hand
55. Anti-patterns: Summary - Keep discussion/review iteration short - Revise the design doc even during implementation - Make responsibility of a design doc clear - Maintain links and a list of design docs
56. Topics - Introduction - Contents of design doc - Anti-patterns - Case study
57. Case study Refactoring task of “setting screen” Notification Graphic quality Animation << ON >> << HIGH >> << FULL >>
58. Meeting for task assignment Clarify objective and background of the tasks
59. Investigation of classes to refactor Investigate current status and clarify the issues
60. Investigation of classes to refactor (cont.) Investigate current status and clarify the issues - Revise sections of objective and background
61. Discussion to decide strategy Discuss design proposals at 1-on-1 with tech-lead, etc.
62. Sections to be added or revised 1/2 Objective/background - Concretization by design proposal Task plan - Implementation order - Modification by other developers during refactoring
63. Sections to be added or revised 2/2 Test - Unit test targets - Regression test targets Procedure to add a new item - Sample code
64. Case study: Summary It is easy to write design doc during discussion
65. Summary Design doc: Document of software design - Clarify the purpose of the document - Write necessary and sufficient sections - Keep cycle for discussion and revising short
66. Appendix 1: Tools Requires features of co-editing, history, and comments - Atlassian confluence, Notion - GitHub Gist, markdown in repository - Google docs, Dropbox Paper, Box notes
67. Appendix 2: Design doc examples Chromium design docs - https://www.chromium.org/developers/design-documents Bazel design docs - https://github.com/bazelbuild/proposals