Jessica Parsons

@verythorough

slides.com/verythorough/ddd-wtd

Lessons Learned From a Year of Docs-Driven Development

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

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

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