Jessica Parsons


Lessons Learned From a Year of Docs-Driven Development

Documentation Engineer


Jessica Parsons


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 out

Is 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


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

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

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!

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

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  

Read for speed


doesn't guarantee


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




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

  • 7,903