2018-01-31 01:36:50 +08:00
|
|
|
# Philosophy
|
|
|
|
|
|
|
|
|
|
埏埴以為器，當其無，有器之用.
|
|
|
|
|
|
|
|
|
|
*Clay becomes pottery through craft, but it's the emptiness that makes a pot
|
|
|
|
|
useful.*
|
|
|
|
|
|
|
|
|
|
\- [Laozi](http://ctext.org/dictionary.pl?if=en&id=11602)
|
|
|
|
|
|
|
|
|
|
Contents:
|
|
|
|
|
|
|
|
|
|
1. [Radical simplicity](#radical-simplicity)
|
|
|
|
|
1. [Readable source text](#readable-source-text)
|
|
|
|
|
1. [Minimum viable documentation](#minimum-viable-documentation)
|
|
|
|
|
1. [Better is better than perfect](#better-is-better-than-perfect)
|
|
|
|
|
|
|
|
|
|
## Radical simplicity
|
|
|
|
|
|
|
|
|
|
* **Scalability and interoperability** are more important than a menagerie of
|
|
|
|
|
unessential features. Scale comes from simplicity, speed, and ease.
|
2019-10-08 17:00:23 +08:00
|
|
|
Interoperability comes from unadorned, digestible content.
|
2018-01-31 01:36:50 +08:00
|
|
|
|
|
|
|
|
* **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 [Best Practices](best_practices.md).
|
|
|
|
|
|
|
|
|
|
* **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.
|
