埏埴以為器，當其無，有器之用.
Clay becomes pottery through craft, but it's the emptiness that makes a pot
useful.
- Laozi
Contents:
Scalability and interoperability are more important than a menagerie of
unessential features. Scale comes from simplicity, speed, and ease.
Interoperability comes from unadorned, digestable content.
Fewer distractions make for better writing and more productive reading.
New features should never interfere with the simplest use case and should
remain invisible to users who don't need them.
This guide is designed for the average engineer -- the busy,
just-want-to-go-back-to-coding engineer. Large and complex documentation is
possible but not the primary focus.
Minimizing context switching makes people happier. Engineers should be
able to interact with documentation using the same tools they use to read and
write code.
Plain text not only suffices, it is superior. Markdown itself is not
essential to this formula, but it is the best and most widely supported
solution right now. HTML is generally not encouraged.
Content and presentation should not mingle. It should always be possible
to ditch the renderer and read the essential information at source. Users
should never have to touch the presentation layer if they don't want to.
Portability and future-proofing leave room for the unimagined integrations
to come, and are best achieved by keeping the source as human-readable as
possible.
Static content is better than dynamic, because content should not depend
on the features of any one server. However, fresh is better than stale. We
strive to balance these needs.
Docs thrive when they're treated like tests: a necessary chore one learns
to savor because it rewards over time.
See Best Practices.
Brief and utilitarian is better than long and exhaustive. The vast
majority of users need only a small fraction of the author's total knowledge,
but they need it quickly and often.
Incremental improvement is better than prolonged debate. Patience and
tolerance of imperfection allow projects to evolve organically.
Don't lick the cookie, pass the plate. We're drowning in potentially
impactful projects. Choose only those you can really handle and release those
you can't.
