Philosophy

Background

Introduction

埏埴以為器，當其無，有器之用.

Clay becomes pottery through craft, but it’s the emptiness that makes a pot useful.

• Laozi

Radical simplicity

• Scalability and interoperability are more important than a menagerie of unessential features. Scale comes from simplicity, speed, and ease. Interoperability comes from unadorned, digestible 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.

Readable source text

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

Minimum viable documentation

• Docs thrive when they’re treated like tests: a necessary chore one learns to savor because it rewards over time. See Documentation 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.

Better is better than perfect

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