1# Philosophy
2
3埏埴以為器，當其無，有器之用.
4
5*Clay becomes pottery through craft, but it's the emptiness that makes a pot
6useful.*
7
8\- [Laozi](http://ctext.org/dictionary.pl?if=en&id=11602)
9
10Contents:
11
121.  [Radical simplicity](#radical-simplicity)
131.  [Readable source text](#readable-source-text)
141.  [Minimum viable documentation](#minimum-viable-documentation)
151.  [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