Add option philosophy to docs (#3855)

docs/option-philosophy.md

@@ -0,0 +1,28 @@
+---
+id: option-philosophy
+title: Option Philosophy
+---
+
+Prettier is not a kitchen-sink code formatter that attempts to print your code in any way you wish. It is _opinionated._ Quoting the [Why Prettier?](why-prettier.md) page:
+
+> By far the biggest reason for adopting Prettier is to stop all the on-going debates over styles.
+
+The more options Prettier has, the further from the above goal it gets. **The debates over styles just turn into debates over which Prettier options to use.**
+
+The issue about [resisting adding configuration](https://github.com/prettier/prettier/issues/40) has more 👍s than any option request issue.
+
+So why does Prettier have options at all?
+
+Well, had Prettier been created around the same time as JavaScript itself was born it could have made choices that the community would have picked up (which is the case for [elm-format](https://github.com/avh4/elm-format/)). But JavaScript is far older than Prettier so the community has had time to start their holy wars about tabs vs spaces, single vs double quotes, indentation levels, trailing commas and semicolons, so Prettier more or less has to support those.
+
+Then there's a bunch of interesting cases.
+
+* `--trailing-comma es5` was added to make it easier to use trailing commas in most environments without having to transpile (trailing function commas were added in ES2017).
+* `--prose-wrap` is important to support all quirky markdown renderers in the wild.
+* `--arrow-parens` was added after [huge demand](https://github.com/prettier/prettier/issues/812). Prettier has to strike a balance between ideal goals and listening to the community.
+* `--jsx-bracket-same-line` was needed for a big company with a huge code base (Facebook), which backed the project when it got started, to be able to [adopt Prettier at all](https://github.com/prettier/prettier/pull/661#issuecomment-295770645).
+
+Finally, perhaps the most interesting of them all is `--bracket-spacing`.
+The truth is that not even [Prettier's creator knows exactly why it exists](https://github.com/prettier/prettier/issues/715#issuecomment-281096495). It was added super early on without much thought. It now serves as an example of the types of options we should avoid.
+
+Remember, it is easy to _add_ features to a program, but hard to remove them.

docs/why-prettier.md

@@ -7,6 +7,8 @@ title: Why Prettier?
 
 By far the biggest reason for adopting Prettier is to stop all the on-going debates over styles. It is generally accepted that having a common style guide is valuable for a project and team but getting there is a very painful and unrewarding process. People get very emotional around particular ways of writing code and nobody likes spending time writing and receiving nits.
 
+So why choose the "Prettier style guide" over any other random style guide? Because Prettier is the only "style guide" that is fully automatic. Even if Prettier does not format all code 100% the way you'd like, it's worth the "sacrifice" given the unique benefits of Prettier, don't you think?
+
 * “We want to free mental threads and end discussions around style. While sometimes fruitful, these discussions are for the most part wasteful.”
 * “Literally had an engineer go through a huge effort of cleaning up all of our code because we were debating ternary style for the longest time and were inconsistent about it. It was dumb, but it was a weird on-going "great debate" that wasted lots of little back and forth bits. It's far easier for us all to agree now: just run Prettier, and go with that style.”
 * “Getting tired telling people how to style their product code.”

website/sidebars.json

@@ -5,6 +5,7 @@
       "why-prettier",
       "comparison",
       "language-support",
+      "option-philosophy",
       "rationale"
     ],
     "Usage": [