1 of 21

Design doc workshop

2nd weekly workshop of Hot Open Source Summer

Self link: https://acmcsuf.com/dd

2 of 21

Overview

In this workshop, we will go over:

  • What is a design doc?
  • Why are design docs important?
  • How to create a design doc.
  • Best practices for collaboration and feedback on design docs.

NOTE: Feel free to ask questions in the chat during the workshop and I will answer them as soon as I am able.

​

​

3 of 21

What is a design doc

Design documents help teams break down complex projects into smaller, more manageable tasks. They also help ensure that everyone is on the same page when it comes to the goals, requirements, and constraints of a project.

NOTE: “Design doc” is synonymous/interchangeable with “Design document”

4 of 21

Why are design docs important?

  • Design documents serve as blueprints for software development and implementation. They provide a comprehensive overview of the system's architecture, design principles, and functionality.
  • Design documents facilitate collaboration and maintain a clear understanding of project objectives.

5 of 21

Why are design docs important? (continued)

  • Design documents make you carefully consider your project and help you discover important things you might have overlooked if you hadn't thought about them earlier.
  • At any stage of a project, even with limited information, design documents are valuable tools for brainstorming, organizing thoughts, and fostering collaboration. Design documents help embrace flexibility and iterative updates to accommodate new information and/or changing requirements.

6 of 21

Benefits of planning and prior decision making

“A failure to plan is a plan to fail”

Proper planning and decision-making simplify the development process. Well-designed plans save time and effort. Effective decision-making streamlines workflow, increases productivity, and ensures efficiency.

7 of 21

Keeping documents fresh

  • Updating design documents maintains project clarity and communicates changes.
  • Document reasons for deviations from the original plan.
  • Regular updates enable informed decision-making and adaptation to changing requirements.

​

8 of 21

Alternative solutions

  • The Alternative Solutions section in a design document explores various approaches to address design challenges.
  • It encourages critical thinking, creativity, and informed decision-making.
  • Benefits of the Alternative Solutions section:
    • Enables evaluation of multiple options and their pros and cons.
    • Facilitates the identification of the most suitable solution.
    • Allows for adaptability, mitigating potential issues and enabling necessary pivots.
  • Documenting rationale and trade-offs helps stakeholders understand the decision-making process.
  • Arrive at optimal design choices.

9 of 21

Mitigating issues

  • Include an alternative solutions section in the design document.
  • Explore different approaches to address design challenges.
  • Document rationale and trade-offs to make informed decisions.

​

10 of 21

Popular design document sections

Design documents have a consistent structure, making them easier to understand for people who are already familiar with the patterns commonly found. Listed are several examples of sections commonly used in design documents.

  • Introduction: Overview, purpose, and audience.
  • System Overview: High-level architecture and components.
  • Design Principles and Guidelines: Best practices and standards.
  • Architecture and Component Design: Detailed design of system components.
  • Data Design: Database structure, relationships, and data handling.
  • User Interface Design: User interaction flows and visual design.
  • Error Handling and Exception Management: Strategies for handling errors and exceptions.
  • Testing and Quality Assurance: Approaches for testing and ensuring quality.
  • Deployment and Infrastructure: Deployment architecture and environment setup.
  • Maintenance and Support: Plans for maintenance, upgrades, and support.
  • Time estimates: How long the engineers expect the engineering to take.

11 of 21

Writing insights/tips

  • Keep the document concise and focused.
  • Define the target audience clearly.
  • Use diagrams and visuals to enhance understanding.
  • Prioritize clarity and simplicity in writing.
  • Justify design choices with reasoning and rationale.
  • Consider scalability and extensibility of the system.
  • Gather feedback from team members for better outcomes.
  • Update the document as the project progresses.
  • Review the document from a newcomer's perspective.
  • Continuously improve design documentation skills.
  • Creativity is welcome as long as it does not distract from relevant topics; use creativity to inspire curiosity and interest in the project.
  • Practice makes perfect!
  • Use LLMs (e.g. ChatGPT) for outlining!

12 of 21

Review cycle

​

​

Essential for ensuring document quality and collaboration.

  • Writer's Etiquette:
    • Be open to feedback and constructive criticism.
    • Clearly communicate the purpose and context of the document.
    • Respond promptly to reviewer comments and questions.
    • Consider suggestions and incorporate relevant changes into the document.
    • Maintain a positive and professional attitude throughout the review process.
  • Reviewer's Etiquette:
    • Provide specific and actionable feedback.
    • Focus on the content and objectives of the document.
    • Offer suggestions for improvement rather than just pointing out flaws.
    • Be respectful and considerate in your comments and tone.
    • Seek clarification when necessary and engage in a constructive dialogue.

13 of 21

Review cycle benefits

​

​

  • Ensures accuracy and quality of the design document.
  • Enhances collaboration and knowledge sharing within the team.
  • Helps identify potential issues or gaps in the design early on.
  • Provides multiple perspectives and diverse insights for improvement.
  • Promotes a culture of continuous learning and growth.

​

14 of 21

Review cycle best practices

  • Establish a clear review process with defined roles and responsibilities.
  • Set realistic timelines for review and incorporate buffer time for revisions.
  • Provide guidelines or a checklist for reviewers to follow.
  • Encourage open communication and discussions during the review.
  • Document and track the changes made based on the review feedback.
  • Appreciate and acknowledge the contributions of reviewers.

​

15 of 21

Collaboration best practices

  • Effective communication:
    • Foster open and transparent communication channels.
    • Actively listen and seek to understand others' perspectives.
    • Clearly articulate ideas, expectations, and concerns.
    • Use collaboration tools to streamline communication.
  • Clearly defined roles and responsibilities:
    • Assign roles and responsibilities to team members.
    • Ensure everyone understands their tasks and deadlines.
    • Encourage accountability and ownership of assigned work.
  • Regular team meetings and updates:
    • Schedule regular team meetings to discuss progress and challenges.
    • Share updates, insights, and important information.
    • Encourage active participation and collaboration during meetings.
  • Collaborative decision-making:
    • Involve team members in decision-making processes.
    • Seek input and feedback from diverse perspectives.
    • Foster a culture of respectful discussion and consensus-building.

16 of 21

Collaboration best practices (continued)

  • Constructive feedback and recognition:
    • Provide constructive feedback to promote growth and improvement.
    • Recognize and appreciate team members' contributions.
    • Foster a positive and supportive environment.
  • Conflict resolution
    • Address conflicts promptly and professionally.
    • Encourage open dialogue and understanding among team members.
    • Seek win-win solutions and compromise when necessary.
  • Continuous learning and knowledge sharing:
    • Encourage ongoing learning and skill development.
    • Foster a culture of knowledge sharing and documentation.
    • Celebrate and share successful project outcomes.

​

​

17 of 21

Examples

Let’s jump right into some examples. I started design documents for several of our club’s open source software initiatives.

18 of 21

Q&A

  • Questions?
    • How to choose diagrams for your design document.
      • It is profession to create appealing visual representations, but keep in mind that it is easier to edit text-based diagrams.
    • Does the order of operations matter?
      • Getting a server up and running, for example.
        • You want to guarantee that the deployment pipeline is working. Choose a deployment provider beforehand and keep it in mind in development.
    • System design interviews.
      • Senior developers evolve from junior developers. Junior developers are not generally required to pass system design interview. It comes from experience, so nothing to worry about because you will be ready when the time comes.
      • Add design document experience into your experience section. Experience sections show what you learned on the job and did to improve the company.
    • Design documents are a very interdisciplinary skill.
  • Personal experiences?
    • Bug bash/bounty is fun :) -- we should do that for the acmcsuf.com redesign.

19 of 21

Conclusion

In conclusion, design documents are widely used to facilitate brainstorming, provide structure, and support project development at any stage, with the understanding that they will be updated and iterated upon as progress continues.��NOTE: Practice makes perfect; keep writing!

20 of 21

Conclusion

See you next time! Thank you for coming.

​

NOTE: Please do not hesitate to share any future workshop topic ideas for next Wednesday’s "Open Source Software" Summer Hackathon workshop!!

21 of 21

More resources