07 Design Docs

  • Types of documentation

    • Reference documentation (incl. code comments)
    • Design documents
    • Tutorials
    • Conceptual documentation
    • Landing pages

  • Design documents

    • Code review before there is code!
    • Collaborative (Google Docs)
    • Ensure various concerns are covered, such as: security implications, internationalization, storage requirements, and privacy concerns.
    • A good design doc should cover
      • Goals and use cases for the design
      • Implementation ideas (not too specific!)
      • Propose key design decisions with an emphasis on their individual tradeoffs
    • The best design docs suggest design goals, and cover alternative designs, documenting the strengths and weaknesses of each.
    • The worst design docs accidentally embed ambiguities, which cause implementors to develop contradictory solutions that the customer doesn’t want.

  • Common parts/templates

    1. Metadata: version, date, authors
    2. Executive Summary: problem being solved, project mission
    3. Stakeholders (and non-stakeholders)
    4. Scenarios / User Stories

    5. User Experience

    6. High-level Requirements: Functional • Global Requirements: Quality, Security, Privacy, Ethics

    7. Features and Operations
    8. Design Considerations and Tradeoffs
    9. Non-Goals
    10. Roadmap / Timeline
    11. Open Issues

  • Examples: SourceGraph RFCs