Writing Design Docs for Wide Audiences

Writing Design Docs
For Wide Audiences
Michele Titolo

Software Engineer, Square

@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

@micheletitolo
Figure Out Your Audience

@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
•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

@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

@micheletitolo
Design Docs Are Not
End User
Documentation

@micheletitolo
Design Docs Do Take
Time To Write

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

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

@micheletitolo
Writing Design Docs Is a
Skill, Can Improve

@micheletitolo
Increase Your Impact 💪

• 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

Writing Design Docs for Wide Audiences

More Related Content

Similar to Writing Design Docs for Wide Audiences

More from Michele Titolo

Recently uploaded

Writing Design Docs for Wide Audiences