Finding a Home for Docs

Jessica Parsons

@verythorough

slides.com/verythorough/home-for-docs

All images from Disney/Pixar's Up

Who am I?

Documentation Engineer

GoTrue  ⬩  Git Gateway

GoCommerce  ⬩  GoTell

Who am I?

Documentarian Supporter

What are we talking about?

Where to store the docs "source"

  • Docs for open source projects, managed as code
     
  • Mostly written in Markdown and JSON/YAML/TOML
     
  • Generally managed with Git, stored in GitHub

Why does it matter?

Optimizing for all parties

  • Users
     
  • Contributors
     
  • Maintainers
     

What are the options?

Comparing the neighborhoods

  • Docs stored in repo with project code
     
  • Docs in their own repo
     
  • Hybrid
     

Story Time

About the evolution of docs
for Netlify CMS

Docs with code, in GitHub

Docs with code, in GitHub

Docs with code, in GitHub

Making a "real" website

Docs get a new home

...but living in two houses

Adding some magic

Adding some magic

Adding some magic

Adding some magic

Making magic is hard

especially when it breaks your other magic

... like Deploy Previews - here's a preview:

Making magic is hard

There must be a better way!

Our considerations for choosing a better path:
 

  • ease of contribution to avoid docs drift
     
  • managing repo size and complexity
     
  • handling legacy versions

Weighing
the Options

Docs in the code repo

Examples

Using GitHub UI for display:

✨ Markdown Magic     🔑 GoTrue

Building to a website:

Docs in the code repo

What makes this a happy path

  • can view together in same repo, even offline
     
  • docs edits can be required in same PR
     
  • easy tie-ins to code-comment docs

Connecting docs with code

Docs in the code repo

What makes this a happy path

  • GitHub UI does automatically
      (assuming docs are up to date with release)
     
  • could also work well with tag-based deploys

Tying past versions to releases

Docs in the code repo

Potential bumps in the road

  • Look generic
     
  • Can be unwelcoming to GitHub newcomers
     
  • Can require repetition for nav, etc.

GitHub UI docs are limited

Docs in the code repo

Potential bumps in the road

  • Lots of non-docs content?
     
  • Media heavy?
     
  • Versions stored in subdirectories?

Repo size and complexity

Docs in the code repo

Potential bumps in the road

  • Can publish to a 'next' branch until release
     
  • Docusaurus: built-in handling with subfolders
     
  • Video.js docs use a script to stop publishing until release tagged

Docs can get ahead of release

Docs in their own repo

Examples

Multi-repo sites:

Docs in their own repo

What makes this a happy path

  • Docs for many interlinked projects (Docker)
     
  • Media-heavy docs or multi-purpose sites
     
  • Better for subfolder versioning
      (but branch versioning is often better)
     
  • Supports specialized maintainer teams

Separation of concerns for bigger projects

Docs in their own repo

Potential bumps in the road

  • Docs updates can be overlooked
    • ​make a docs PR a requirement for merge
       
  • Versions aren't automatically tied to releases
    • ​won't drift ahead
    • can require complete docs for release

    •  

Docs drift risk

Docs in their own repo

Potential bumps in the road

Docs contributors don't count in code repo

A hybrid approach

Examples

Separate docs and marketing sites:

Pull docs content into site:

A hybrid approach

What makes this a happy path

  • Keep docs close to code
     
  • Keep heavier content separate
    ​
  • Doesn't have to be all that complicated
      (particularly if built as separate sites)

Getting the best of both worlds

A hybrid approach

Potential bumps in the road

  • Risk of style drift when maintaining separate sites
     
  • Complex setup when pulling multi-repo content into a single site

Setup or maintenance can be difficult

Where did we settle?

Docs came home to live with code

Where did we settle?

Docs came home to live with code

One final tip:

No matter where you store your docs,

let people know where to find them!

Thank you!

slides.com/verythorough