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