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