styleguide/docguide/philosophy.md
amanvell 257e420170
Spelling mistake
Minor spelling mistake
2019-10-08 20:00:23 +11:00

72 lines
2.7 KiB
Markdown

# 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.
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 [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.