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

Introduction To
Design Docs

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

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

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

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

@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

@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

@micheletitolo
•Collaborative editor
•Single place of truth
•Single place of discussion
Where Do You Write
A Design Doc

How To Write A
Design Doc

@micheletitolo
Figure Out Your Audience

@micheletitolo
Vertical

@micheletitolo
Vertical, Horizontal

@micheletitolo
Vertical, Horizontal, Both

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

@micheletitolo
Sections

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

@micheletitolo
No PRD? Write
Requirements In A Section

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

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

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

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

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

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

@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

@micheletitolo
Adoption Takes Time

Writing Effectively

@micheletitolo
•The Elements of Style, William Strunk JR and E.B. White
•Google Developer's Technical Writing Courses
Resources For Improving
Your Writing

@micheletitolo
⚠Warning⚠:
Bikeshedding Ahead

@micheletitolo
•A design doc is not a manifesto
•Liberally use non-goals to set boundaries
•Ground concerns with facts
Dealing With
Controversial Topics

@micheletitolo
"The Monolith Does Not Scale"

@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."

@micheletitolo
Write With Intention Of
Building Alignment

Gotchas

@micheletitolo
Design Docs Are Not
End User
Documentation

@micheletitolo
Design Docs Do Take
Time To Write

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

Conclusion

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

@micheletitolo
Writing Design Docs Is a
Skill, Can Improve

@micheletitolo
Increase Your Impact 💪

@micheletitolo
Thank You

• 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