Upgrade to Pro — share decks privately, control downloads, hide ads and more …

How to Write a Design Doc (En ver.)

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

Munetoshi Ishikawa

May 11, 2023
Tweet

More Decks by Munetoshi Ishikawa

Other Decks in Programming

Transcript

  1. Note for this session Many different styles and methodologies for

    design docs - This session introduces only one of them - Customize if you need to 

  2. 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
  3. Introduction - What a design doc is - What to

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

    write - When to write - Comparison with waterfall
  5. What a design doc is 1/2 Document for software design

    - Focuses on how to solve - Written by developers
  6. 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/
  7. 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
  8. Introduction - What a design doc is - What to

    write - When to write - Comparison with waterfall
  9. Main purpose Focuses on “how to implement” - Clarification problem

    and solution - Discussion with team members - Record as background of the implementation
  10. 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
  11. Number of pages A few pages to a dozen pages

    - Short is preferred - Split a task/project if the document becomes too long
  12. Introduction - What a design doc is - What to

    write - When to write - Comparison with waterfall
  13. 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
  14. 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
  15. Introduction - What a design doc is - What to

    write - When to write - Comparison with waterfall
  16. 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
  17. 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/
  18. Introduction: Summary Document for software design - Focusing on “how

    to solve” - For large/middle task - Updatable during implementation
  19. Format of design docs No concrete format, basically - Comprising

    of necessary and sufficient sections - “Fill in the format” is not the objective
  20. Typical design doc contents - Objective/goal (required for most cases)

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

    - Background - Design overview - Design details - Concerns
  22. Objective/goal Explain “what to realize” in a few sentences -

    “FOO achieves…” - “BAR is a new API to replace…” - “This refactoring is to simplify…”
  23. 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
  24. Typical design doc contents - Objective/goal (required for most cases)

    - Background - Design overview - Design details - Concerns
  25. 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…
  26. 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
  27. 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/
  28. Typical design doc contents - Objective/goal (required for most cases)

    - Background - Design overview - Design details - Concerns
  29. Design overview Write/draw only important points - Basic ideas for

    the implementation - Simplified class/module diagrams - List of important entities and descriptions
  30. 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…"
  31. Design overview: Note Do not write/draw too much details -

    Focuses only on important elements - Omit unimportant elements simplify
  32. Typical design doc contents - Objective/goal (required for most cases)

    - Background - Design overview - Design details - Concerns
  33. 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
  34. 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
  35. Typical design doc contents - Objective/goal (required for most cases)

    - Background - Design overview - Design details - Concerns
  36. Concerns Task management, affected features, and other concerns - Contact

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

    issues and limitations - Affected modules - Security, privacy, performance
  38. Typical design doc contents - Objective/goal (required for most cases)

    - Background - Design overview - Design details - Concerns
  39. 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
  40. 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
  41. 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
  42. Anti-pattern 2 1. Finish design doc review 2. Start implementation

    3. A structural problem found 4. Workaround with ad-hoc patch
  43. When to update Modify the design even during implementation Discuss

    “how to solve” in a short cycle - Revise the design doc if required
  44. 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
  45. 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, …
  46. 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
  47. 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
  48. 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
  49. Investigation of classes to refactor (cont.) Investigate current status and

    clarify the issues - Revise sections of objective and background
  50. Sections to be added or revised 1/2 Objective/background - Concretization

    by design proposal Task plan - Implementation order - Modification by other developers during refactoring
  51. Sections to be added or revised 2/2 Test - Unit

    test targets - Regression test targets Procedure to add a new item - Sample code
  52. 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
  53. 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