Slide 1

Slide 1 text

Munetoshi Ishikawa How to Write a Design Doc

Slide 2

Slide 2 text

Note for this session Many different styles and methodologies for design docs - This session introduces only one of them - Customize if you need to 


Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

Topics - Introduction - Contents of design doc - Anti-patterns - Case study

Slide 5

Slide 5 text

Topics - Introduction - Contents of design doc - Anti-patterns - Case study

Slide 6

Slide 6 text

Introduction - What a design doc is - What to write - When to write - Comparison with waterfall

Slide 7

Slide 7 text

Introduction - What a design doc is - What to write - When to write - Comparison with waterfall

Slide 8

Slide 8 text

What a design doc is 1/2 Document for software design - Focuses on how to solve - Written by developers

Slide 9

Slide 9 text

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/

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

Introduction - What a design doc is - What to write - When to write - Comparison with waterfall

Slide 12

Slide 12 text

Main purpose Focuses on “how to implement” - Clarification problem and solution - Discussion with team members - Record as background of the implementation

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

Number of pages A few pages to a dozen pages - Short is preferred - Split a task/project if the document becomes too long

Slide 15

Slide 15 text

Introduction - What a design doc is - What to write - When to write - Comparison with waterfall

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

Introduction - What a design doc is - What to write - When to write - Comparison with waterfall

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

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/

Slide 21

Slide 21 text

Introduction: Summary Document for software design - Focusing on “how to solve” - For large/middle task - Updatable during implementation

Slide 22

Slide 22 text

Topics - Introduction - Contents of design doc - Anti-patterns - Case study

Slide 23

Slide 23 text

Format of design docs No concrete format, basically - Comprising of necessary and sufficient sections - “Fill in the format” is not the objective

Slide 24

Slide 24 text

Typical design doc contents - Objective/goal (required for most cases) - Background - Design overview - Design details - Concerns Section order: top-down approach

Slide 25

Slide 25 text

Typical design doc contents - Objective/goal (required for most cases) - Background - Design overview - Design details - Concerns

Slide 26

Slide 26 text

Objective/goal Explain “what to realize” in a few sentences - “FOO achieves…” - “BAR is a new API to replace…” - “This refactoring is to simplify…”

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

Typical design doc contents - Objective/goal (required for most cases) - Background - Design overview - Design details - Concerns

Slide 29

Slide 29 text

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…

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

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/

Slide 32

Slide 32 text

Typical design doc contents - Objective/goal (required for most cases) - Background - Design overview - Design details - Concerns

Slide 33

Slide 33 text

Design overview Write/draw only important points - Basic ideas for the implementation - Simplified class/module diagrams - List of important entities and descriptions

Slide 34

Slide 34 text

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…"

Slide 35

Slide 35 text

Design overview: Simplified diagrams Explain important classes and relationships - Hand-drawn diagrams are acceptable

Slide 36

Slide 36 text

Design overview: Note Do not write/draw too much details - Focuses only on important elements - Omit unimportant elements simplify

Slide 37

Slide 37 text

Typical design doc contents - Objective/goal (required for most cases) - Background - Design overview - Design details - Concerns

Slide 38

Slide 38 text

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

Slide 39

Slide 39 text

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

Slide 40

Slide 40 text

Typical design doc contents - Objective/goal (required for most cases) - Background - Design overview - Design details - Concerns

Slide 41

Slide 41 text

Concerns Task management, affected features, and other concerns

Slide 42

Slide 42 text

Concerns Task management, affected features, and other concerns - Contact points - Rough task ordering - Plan of release and monitoring

Slide 43

Slide 43 text

Concerns Task management, affected features, and other concerns - Known issues and limitations - Affected modules - Security, privacy, performance

Slide 44

Slide 44 text

Typical design doc contents - Objective/goal (required for most cases) - Background - Design overview - Design details - Concerns

Slide 45

Slide 45 text

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

Slide 46

Slide 46 text

Topics - Introduction - Contents of design doc - Anti-patterns - Case study

Slide 47

Slide 47 text

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

Slide 48

Slide 48 text

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

Slide 49

Slide 49 text

Anti-pattern 2 1. Finish design doc review 2. Start implementation 3. A structural problem found 4. Workaround with ad-hoc patch

Slide 50

Slide 50 text

When to update Modify the design even during implementation Discuss “how to solve” in a short cycle - Revise the design doc if required

Slide 51

Slide 51 text

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

Slide 52

Slide 52 text

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, …

Slide 53

Slide 53 text

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

Slide 54

Slide 54 text

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

Slide 55

Slide 55 text

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

Slide 56

Slide 56 text

Topics - Introduction - Contents of design doc - Anti-patterns - Case study

Slide 57

Slide 57 text

Case study Refactoring task of “setting screen” Notification Graphic quality Animation << ON >> << HIGH >> << FULL >>

Slide 58

Slide 58 text

Meeting for task assignment Clarify objective and background of the tasks

Slide 59

Slide 59 text

Investigation of classes to refactor Investigate current status and clarify the issues

Slide 60

Slide 60 text

Investigation of classes to refactor (cont.) Investigate current status and clarify the issues - Revise sections of objective and background

Slide 61

Slide 61 text

Discussion to decide strategy Discuss design proposals at 1-on-1 with tech-lead, etc.

Slide 62

Slide 62 text

Sections to be added or revised 1/2 Objective/background - Concretization by design proposal Task plan - Implementation order - Modification by other developers during refactoring

Slide 63

Slide 63 text

Sections to be added or revised 2/2 Test - Unit test targets - Regression test targets Procedure to add a new item - Sample code

Slide 64

Slide 64 text

Case study: Summary It is easy to write design doc during discussion

Slide 65

Slide 65 text

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

Slide 66

Slide 66 text

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

Slide 67

Slide 67 text

Appendix 2: Design doc examples Chromium design docs - https://www.chromium.org/developers/design-documents Bazel design docs - https://github.com/bazelbuild/proposals