Successfully reported this slideshow.

Writing Design Docs for Wide Audiences

0

Share

Loading in …3
×
1 of 43
1 of 43

Writing Design Docs for Wide Audiences

0

Share

Download to read offline

What would you do to convince a large audience, who has little context, to use your solution to a problem? One way is to write a design document, which helps scale technical communication and build alignment among stakeholders. The wider the scope of the problem, the more important alignment is. A design document achieves this by addressing three key questions: “what is the goal?”, “how will we achieve it?” and “why are we doing it this way?”. This talk will cover identifying your audience, effectively writing answers to these questions, and involving the right people at the right time.

What would you do to convince a large audience, who has little context, to use your solution to a problem? One way is to write a design document, which helps scale technical communication and build alignment among stakeholders. The wider the scope of the problem, the more important alignment is. A design document achieves this by addressing three key questions: “what is the goal?”, “how will we achieve it?” and “why are we doing it this way?”. This talk will cover identifying your audience, effectively writing answers to these questions, and involving the right people at the right time.

More Related Content

Related Books

Free with a 14 day trial from Scribd

See all

Related Audiobooks

Free with a 14 day trial from Scribd

See all

Writing Design Docs for Wide Audiences

  1. 1. Writing Design Docs For Wide Audiences Michele Titolo Software Engineer, Square
  2. 2. Introduction To Design Docs
  3. 3. @micheletitolo •Details what you plan to build •Future looking •Has sections or a template What Is A Design Doc
  4. 4. @micheletitolo •Communication •Collaboration •Building alignment •Thoroughness Purpose Of Design Docs
  5. 5. @micheletitolo •Socialize designs •Leverage experiences of others •Reduce surprises Bene fi ts
  6. 6. @micheletitolo •Design docs reference PRDs •Di ff erent purposes PRDs and Design Docs
  7. 7. @micheletitolo •Projects with non-obvious or new components •Cross-team or cross-function •During planning, before implementation •Aid in breaking down the project When Do You Write A Design Doc
  8. 8. @micheletitolo •Prototype before or while writing the design doc •Inform design •Turn unknown unknowns to known unknowns •Timebox or constrain prototype •Link to notes Prototyping
  9. 9. @micheletitolo •Collaborative editor •Single place of truth •Single place of discussion Where Do You Write A Design Doc
  10. 10. How To Write A Design Doc
  11. 11. @micheletitolo Figure Out Your Audience
  12. 12. @micheletitolo Vertical
  13. 13. @micheletitolo Vertical, Horizontal
  14. 14. @micheletitolo Vertical, Horizontal, Both
  15. 15. @micheletitolo •Who will this impact? •Who will integrate? •Who will ultimately use? •Do you have other stakeholders? Research
  16. 16. @micheletitolo Sections
  17. 17. @micheletitolo •Reviewers •Audience •Background •Goals and Non-Goals •Architecture or Design De fi ne The Sections
  18. 18. @micheletitolo No PRD? Write Requirements In A Section
  19. 19. @micheletitolo •History and context •Constraints or challenges Writing The Background
  20. 20. @micheletitolo •Set scope of the doc •Use cases and non use cases •Articulate technical requirements Goals And Non-Goals
  21. 21. @micheletitolo •Describe what you plan to build •Choose the right level of detail •Room for surprises •Tradeo ff s Architecture
  22. 22. @micheletitolo Do Write Api Contracts Don't Write Implementation Code
  23. 23. @micheletitolo •Each visual should have 1 purpose •Always describe the visual •Copy anything numbered out of picture Using Visuals
  24. 24. @micheletitolo •Security •Compliance •Cloud Costs •Monitoring / Alerting / SLOs / SLAs •Disaster recovery •Estimates or Milestone breakdown Other Sections
  25. 25. @micheletitolo •Start small •Get buy in on design doc before •Circulate with reviewers fi rst, then broadly •Design review meeting Building A Design Doc Culture
  26. 26. @micheletitolo Adoption Takes Time
  27. 27. Writing Effectively
  28. 28. @micheletitolo •The Elements of Style, William Strunk JR and E.B. White •Google Developer's Technical Writing Courses Resources For Improving Your Writing
  29. 29. @micheletitolo ⚠Warning⚠: Bikeshedding Ahead
  30. 30. @micheletitolo •A design doc is not a manifesto •Liberally use non-goals to set boundaries •Ground concerns with facts Dealing With Controversial Topics
  31. 31. @micheletitolo "The Monolith Does Not Scale"
  32. 32. @micheletitolo "In order to serve X requests per second, the monolith needs to scale to Y nodes. This will likely cause issues with the database, which is limited to Z concurrent connections."
  33. 33. @micheletitolo Write With Intention Of Building Alignment
  34. 34. Gotchas
  35. 35. @micheletitolo Design Docs Are Not End User Documentation
  36. 36. @micheletitolo Design Docs Do Take Time To Write
  37. 37. @micheletitolo "I Don't Have Time For This"
  38. 38. Conclusion
  39. 39. @micheletitolo E ff ective Design Docs Constantly Work Towards Their Goal
  40. 40. @micheletitolo Writing Design Docs Is a Skill, Can Improve
  41. 41. @micheletitolo Increase Your Impact 💪
  42. 42. @micheletitolo Thank You
  43. 43. • https://unsplash.com/photos/VX87WVuVblk • https://unsplash.com/photos/SGn8Pl-EYq4 • https://unsplash.com/photos/aMioYew5mNE • https://unsplash.com/photos/QIUR-K3YgDk • https://unsplash.com/photos/294j9hG1N3w Photo Credits

×