Jessica Parsons
@verythorough
slides.com/verythorough/ddd-wtd
Documentation Engineer
at
Jessica Parsons
@verythorough
slides.com/verythorough/ddd-wtd
What is this, anyway?
Write docs first
then build to match the docs
- Similarly known as:
- docs-driven design
- readme-driven development
- Might take the form of:
- code comments
- spec files
- user-facing docs
But isn't that just...
Behavior-driven development?
Given Book that has not been checked out
And User who is registered on the system
When User checks out a book
Then Book is marked as checked outIs that a doc? No.
User stories or specifications?
Maybe partly, but there's more to it.
Waterfall all over again?
Doesn't have to be.
Can actually be more agile.
But isn't that just...
We had a lot going for us
- Strong leadership support
- Docs valued in the org
- Generally good communicators
but...
Good intentions
are not enough
Oh! I keep forgetting that
I need to write docs first!
I felt guilty for not getting
more coding done.
I'm not sure where to start.
I can explain things better visually.
-
Project templates include required artifacts, like:
- user stories
- "names for all the things"
- API workflow
- customer-facing docs
Tips: Making it happen
Document the process!
- Doc templates give structure and guidance:
- common section headings
- tips for how to approach
- links to examples
Tips: Making it happen
Provide scaffolding
-
Other media may serve the content (or author) better:
- diagrams
- wireframes
- video
Tips: Making it happen
Think beyond the written word
- Designate a leader to hold people to the process. Can be:
- full-time project manager
- rotating project lead
- Make docs work count
- See Tanya Reilly's Being "Glue"
Tips: Making it happen
The docs can't drive themselves
Early docs are useful even as they're
being written
- Identify issues when investment is low:
- Devs adjust plans as they write
- Writers spot issues that spark conversations
Treasures:
Benefits of writing
Leverage team expertise:
They say naming things is one of the hardest things in programming...
Try delegating it to someone
who writes for a living!
Treasures:
Benefits of writing
Writing a doc doesn't mean it will be read
I wrote a doc and
shared it in Slack.
I asked for comments,
but I got crickets.
I don't know when a doc has changed, and I can't tell what's new.
- Specify reviewers and timelines
- one representative from each relevant team
- default review stages with deadlines
- include in sprint planning
Tips: Read the docs!
Add accountability
- Handle with tools
- GitHub PRs & diffs
- Notion updates
- Handle with humans
- file issues for review
- announce changes in project channel
Tips: Read the docs!
Notify readers
When teams do read the docs, they get more efficient
Joining projects midstream
I thought I would need a pairing to catch up, but everything I needed was in the docs!
*also makes projects more inclusive
Treasures:
Read for speed
- Teams with docs can work in parallel:
- Frontend develops against API spec while API builds the endpoints
- Support rep learns the feature in depth in advance
- Marketing preps messaging
- DevRel can plan sample projects
Treasures:
Read for speed
"Docs-driven"
doesn't guarantee
"user-centered"
How do I turn this off?
Tips: Think of the users!
- Beware function-focused user stories
- Get users involved sooner
- Enlist customer-facing teammates:
- support
- community managers
- developer advocates
- sales
School is still
in session
Follow me for updates
@verythorough
Thanks!
slides.com/verythorough/ddd-wtd
@verythorough
Lessons Learned in a Year of Docs-Driven Development
By Jessica Parsons
Lessons Learned in a Year of Docs-Driven Development
What we learned when our company decided to move our product development process from “docs or it didn’t happen” to “docs or it won’t happen.” Presented at Write the Docs Portland 2019. Video at https://youtu.be/WDYQoZ-QDRM
