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.

1. Writing Design Docs
For Wide Audiences
Michele Titolo
Software Engineer, Square

2. Introduction To
Design Docs

3. @micheletitolo
•Details what you plan to build
•Future looking
•Has sections or a template
What Is A Design Doc

4. @micheletitolo
•Communication
•Collaboration
•Building alignment
•Thoroughness
Purpose Of Design Docs

5. @micheletitolo
•Socialize designs
•Leverage experiences of others
•Reduce surprises
Bene
fi
ts

6. @micheletitolo
•Design docs reference PRDs
•Di
ff
erent purposes
PRDs and Design Docs

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. @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. @micheletitolo
•Collaborative editor
•Single place of truth
•Single place of discussion
Where Do You Write
A Design Doc

10. How To Write A
Design Doc

11. @micheletitolo
Figure Out Your Audience

12. @micheletitolo
Vertical

13. @micheletitolo
Vertical, Horizontal

14. @micheletitolo
Vertical, Horizontal, Both

15. @micheletitolo
•Who will this impact?
•Who will integrate?
•Who will ultimately use?
•Do you have other stakeholders?
Research

16. @micheletitolo
Sections

17. @micheletitolo
•Reviewers
•Audience
•Background
•Goals and Non-Goals
•Architecture or Design
De
fi
ne The Sections

18. @micheletitolo
No PRD? Write
Requirements In A Section

19. @micheletitolo
•History and context
•Constraints or challenges
Writing The Background

20. @micheletitolo
•Set scope of the doc
•Use cases and non use cases
•Articulate technical requirements
Goals And Non-Goals

21. @micheletitolo
•Describe what you plan to build
•Choose the right level of detail
•Room for surprises
•Tradeo
ff
s
Architecture

22. @micheletitolo
Do Write Api Contracts
Don't Write
Implementation Code

23. @micheletitolo
•Each visual should have 1 purpose
•Always describe the visual
•Copy anything numbered out of picture
Using Visuals

24. @micheletitolo
•Security
•Compliance
•Cloud Costs
•Monitoring / Alerting / SLOs / SLAs
•Disaster recovery
•Estimates or Milestone breakdown
Other Sections

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. @micheletitolo
Adoption Takes Time

27. Writing Effectively

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. @micheletitolo
⚠Warning⚠:
Bikeshedding Ahead

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. @micheletitolo
"The Monolith Does Not Scale"

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. @micheletitolo
Write With Intention Of
Building Alignment

34. Gotchas

35. @micheletitolo
Design Docs Are Not
End User
Documentation

36. @micheletitolo
Design Docs Do Take
Time To Write

37. @micheletitolo
"I Don't Have Time For
This"

38. Conclusion

39. @micheletitolo
E
ff
ective Design Docs
Constantly Work
Towards Their Goal

40. @micheletitolo
Writing Design Docs Is a
Skill, Can Improve

41. @micheletitolo
Increase Your Impact 💪

42. @micheletitolo
Thank You

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