1 # Philosophy 2 3 . 4 5 *Clay becomes pottery through craft, but it's the emptiness that makes a pot 6 useful.* 7 8 \- [Laozi](http://ctext.org/dictionary.pl?if=en&id=11602) 9 10 Contents: 11 12 1. [Radical simplicity](#radical-simplicity) 13 1. [Readable source text](#readable-source-text) 14 1. [Minimum viable documentation](#minimum-viable-documentation) 15 1. [Better is better than perfect](#better-is-better-than-perfect) 16 17 ## Radical simplicity 18 19 * **Scalability and interoperability** are more important than a menagerie of 20 unessential features. Scale comes from simplicity, speed, and ease. 21 Interoperability comes from unadorned, digestable content. 22 23 * **Fewer distractions** make for better writing and more productive reading. 24 25 * **New features should never interfere with the simplest use case** and should 26 remain invisible to users who don't need them. 27 28 * **This guide is designed for the average engineer** -- the busy, 29 just-want-to-go-back-to-coding engineer. Large and complex documentation is 30 possible but not the primary focus. 31 32 * **Minimizing context switching makes people happier.** Engineers should be 33 able to interact with documentation using the same tools they use to read and 34 write code. 35 36 ## Readable source text 37 38 * **Plain text not only suffices, it is superior**. Markdown itself is not 39 essential to this formula, but it is the best and most widely supported 40 solution right now. HTML is generally not encouraged. 41 42 * **Content and presentation should not mingle**. It should always be possible 43 to ditch the renderer and read the essential information at source. Users 44 should never have to touch the presentation layer if they don't want to. 45 46 * **Portability and future-proofing leave room for the unimagined integrations 47 to come**, and are best achieved by keeping the source as human-readable as 48 possible. 49 50 * **Static content is better than dynamic**, because content should not depend 51 on the features of any one server. However, **fresh is better than stale**. We 52 strive to balance these needs. 53 54 ## Minimum viable documentation 55 56 * **Docs thrive when they're treated like tests**: a necessary chore one learns 57 to savor because it rewards over time. 58 See [Best Practices](best_practices.md). 59 60 * **Brief and utilitarian is better than long and exhaustive**. The vast 61 majority of users need only a small fraction of the author's total knowledge, 62 but they need it quickly and often. 63 64 ## Better is better than perfect 65 66 * **Incremental improvement is better than prolonged debate**. Patience and 67 tolerance of imperfection allow projects to evolve organically. 68 69 * **Don't lick the cookie, pass the plate**. We're drowning in potentially 70 impactful projects. Choose only those you can really handle and release those 71 you can't. 72
