You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: Documentation Levels
slug: documentation-levels
subtitle: for Open Source Projects
category: essay
tags: ['DX', docs, open source, Tech, ideas]
date: 2020-01-29
description: People can't use your code without docs. People might get overwhelmed with too many docs. How can we match the maturity of docs to the maturity of the project?
We had an interesting discussion yesterday on what makes great docs (in this context we are only talking about OSS docs). We all know docs are important, but we can't necessarily articulate what makes good docs. It's more of a "I'll know it when I see it" situation.
No docs is bad.
More docs is good.
A pile of disorganized, out of date docs is bad.
The best docs are the ones I don't have to read (until just before I need them, or visual affordances make them unnecessary).
Can we do better than this vague intuition?
Table of Contents
Matching Maturity
There are docs extremists - they aren't happy until every last thing is spelled out, and they want every project to have tip top docs quality. The thing is, docs do have a maintenance cost, and docs are expensive (in developer time) to write. Possibly the only thing worse than no docs are out-of-date docs that don't help you figure out if they are out of date. The idea of docs driven design is a popular solution for this - if you know you have perfect discipline - but it doesn't answer the question of what kinds of docs you can offer to help the user.
I think we need to articulate a spectrum of acceptable docs. The maturity of docs should match the maturity of the project.
I'm not a technical writer or documentarian so I don't know if there is existing thinking on this, but this is mine so far.
Docs Goals
High level user centric goals of docs:
Beginners: get to success as quickly as possible, avoid/recover from mistakes
Intermediate: contrast with comparable projects, learn every API/option
Experts: keep up with changes and future plans
Contributors: How to contribute, how the project is setup
Docs don't linearly increase in quality with word count. You cannot hedge by throwing more words at a problem.
Try to have your target user persona in mind and write specifically for them, only what they need and what they are about to need.
Use links and other UI options to branch out for other user types.
Be very conscious of visual hierarchy - don't put irrelevant details, in-depth explanations, jokes and anecdotes where someone is looking to get quick hits.
Code examples should be small yet useful - don't dump entire apps that would take more time to customize than it would be to write from scratch.
irrelevant details, in-depth explanations, and anecdotes removed
small! blocks of code
provide a one sentence explanation and example for each term, no more.
run through the example as you make it
Bottom Line Up Front
I call this the Recipe Rule - Recipe Blogs making you scroll through 10 pages of life stories and long walks on the beach before showing the damn recipe.
Example audience: expert user. Needs API stability/migration instructions, deep insight on how the project works and how it can solve problems. Needs to customize/adapt for at-scale/weird usecases
Growing the MetaLanguage
Origin Story/Naming
Who Uses Us
Logos
Quotes/endorsements/testimonials
Link to production use
Funding
Migration docs from previous versions
Roadmap
Reader-friendly Changelog
Anti-Docs
Helping Contributors
Maintainer Responsibilities
Contributor Recognition
How it Works under the hood
CONTRIBUTING.md
Easy Local Edits - when someone spots something wrong, or wants to add something, how easy is it?
A more ambitious framing of this might put them into a pyramid "hierarchy of needs". However I don't think it is appropriate yet at this stage while I explore this idea.
title: Documentation Levels
slug: documentation-levels
subtitle: for Open Source Projects
category: essay
tags: ['DX', docs, open source, Tech, ideas]
date: 2020-01-29
description: People can't use your code without docs. People might get overwhelmed with too many docs. How can we match the maturity of docs to the maturity of the project?
We had an interesting discussion yesterday on what makes great docs (in this context we are only talking about OSS docs). We all know docs are important, but we can't necessarily articulate what makes good docs. It's more of a "I'll know it when I see it" situation.
Can we do better than this vague intuition?
Table of Contents
Matching Maturity
There are docs extremists - they aren't happy until every last thing is spelled out, and they want every project to have tip top docs quality. The thing is, docs do have a maintenance cost, and docs are expensive (in developer time) to write. Possibly the only thing worse than no docs are out-of-date docs that don't help you figure out if they are out of date. The idea of docs driven design is a popular solution for this - if you know you have perfect discipline - but it doesn't answer the question of what kinds of docs you can offer to help the user.
I think we need to articulate a spectrum of acceptable docs. The maturity of docs should match the maturity of the project.
I'm not a technical writer or documentarian so I don't know if there is existing thinking on this, but this is mine so far.
Docs Goals
High level user centric goals of docs:
Quote Dan Abramov:
Brainstorming Docs Features
I tried to loosely order this but ofc it is up to interpretation. A lot of this is my brainstorm, plus Mark's summary of the great Divio blogpost:
Brevity as a MetaFeature
Here's Tania Rascia:
Bottom Line Up Front
I call this the Recipe Rule - Recipe Blogs making you scroll through 10 pages of life stories and long walks on the beach before showing the damn recipe.
Here's David Khourshid:
Levels
I also like Brian Chesky's idea of growing customer experience by hotel analogy. If a 1 star hotel is just a bed, a 3 star hotel has a gym, 4 star has a pool, and 5 star hotel has dining, spa and concierge, etc. What is a 6 star hotel? 10 star? and so on.
So let's split up those features above by levels - and pair the levels with where the project is. Every level includes the prior level.
A more ambitious framing of this might put them into a pyramid "hierarchy of needs". However I don't think it is appropriate yet at this stage while I explore this idea.
Further Reading
The text was updated successfully, but these errors were encountered: