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
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/4573159/serverless.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/4573163/gatsby-word.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/4573203/logo.png)
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
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5185714/scrapbook.jpg)
Docs with code, in GitHub
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/4572858/Screen_Shot_2018-02-03_at_7.12.00_PM.png)
Docs with code, in GitHub
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/4572882/story2.png)
Docs with code, in GitHub
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/4572888/story3.png)
Making a "real" website
Docs get a new home
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/4572899/story4b.png)
...but living in two houses
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/4572898/story4a.png)
Adding some magic
Adding some magic
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/4573178/Screen_Shot_2018-02-04_at_2.44.00_AM.png)
Adding some magic
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/4573180/Screen_Shot_2018-02-04_at_2.39.20_AM.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/4573190/Screen_Shot_2018-02-04_at_2.55.05_AM.png)
Adding some magic
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/4573207/Screen_Shot_2018-02-04_at_3.42.38_AM.png)
Making magic is hard
especially when it breaks your other magic
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/4573220/Screen_Shot_2018-02-04_at_4.29.56_AM.png)
... 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
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5185696/direction.jpg)
Docs in the code repo
Examples
Using GitHub UI for display:
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/4573336/react-static.png)
✨ Markdown Magic 🔑 GoTrue
Building to a website:
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/4573163/gatsby-word.jpg)
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
-
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
- Use all-contributors spec and tools
Docs contributors don't count in code repo
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/4573345/Screen_Shot_2018-02-04_at_8.17.29_AM.png)
A hybrid approach
Examples
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/4573159/serverless.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/4573203/logo.png)
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?
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/4573355/Screen_Shot_2018-02-04_at_7.13.07_AM.png)
Docs came home to live with code
Where did we settle?
Docs came home to live with code
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/4573356/Screen_Shot_2018-02-04_at_7.15.27_AM.png)
One final tip:
No matter where you store your docs,
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/4573357/Screen_Shot_2018-02-04_at_8.45.57_AM.png)
let people know where to find them!
Thank you!
slides.com/verythorough
Finding a Home for Docs
By Jessica Parsons
Finding a Home for Docs
Where docs are stored can impact open source projects in a variety of ways. This talk will present some options, considerations, and guidelines for making an informed decision when choosing a path for docs in current and future projects.
- 4,035