Finding a Home for Docs

Jessica Parsons

@verythorough

slides.com/verythorough/home-for-docs

All images from Disney/Pixar's Up

Who am I?

Who am I?

Documentarian Supporter

What are we talking about?

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

• Users
   
• Contributors
   
• Maintainers
   

What are the options?

• 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

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

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

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.

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

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

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 in their own repo

Potential bumps in the road

• Use all-contributors spec and tools​

Docs contributors don't count in code repo

A hybrid approach

Examples

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)

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

Where did we settle?

Where did we settle?

Docs came home to live with code

One final tip:

No matter where you store your docs,

Thank you!

slides.com/verythorough