Clarify docs about pragma (#10500)

docs/cli.md

@@ -114,22 +114,6 @@ If you don’t have a configuration file, or want to ignore it if it does exist,
 
 Path to a file containing patterns that describe files to ignore. By default, Prettier looks for `./.prettierignore`.
 
-## `--require-pragma`
-
-Require a special comment, called a pragma, to be present in the file’s first docblock comment in order for Prettier to format it.
-
-```js
-/**
- * @prettier
- */
-```
-
-Valid pragmas are `@prettier` and `@format`.
-
-## `--insert-pragma`
-
-Insert a `@format` pragma to the top of formatted files when pragma is absent. Works well when used in tandem with `--require-pragma`.
-
 ## `--list-different`
 
 Another useful flag is `--list-different` (or `-l`) which prints the filenames of files that are different from Prettier formatting. If there are differences the script errors out, which is useful in a CI scenario.

docs/options.md

@@ -267,9 +267,9 @@ This option is only useful in the CLI and API. It doesn’t make sense to use it
 
 _First available in v1.7.0_
 
-Prettier can restrict itself to only format files that contain a special comment, called a pragma, at the top of the file. This is very useful when gradually transitioning large, unformatted codebases to prettier.
+Prettier can restrict itself to only format files that contain a special comment, called a pragma, at the top of the file. This is very useful when gradually transitioning large, unformatted codebases to Prettier.
 
-For example, a file with the following as its first comment will be formatted when `--require-pragma` is supplied:
+A file with the following as its first comment will be formatted when `--require-pragma` is supplied:
 
 ```js
 /**
@@ -293,12 +293,16 @@ or
 
 _First available in v1.8.0_
 
-Prettier can insert a special @format marker at the top of files specifying that the file has been formatted with prettier. This works well when used in tandem with the `--require-pragma` option. If there is already a docblock at the top of the file then this option will add a newline to it with the @format marker.
+Prettier can insert a special `@format` marker at the top of files specifying that the file has been formatted with Prettier. This works well when used in tandem with the `--require-pragma` option. If there is already a docblock at the top of the file then this option will add a newline to it with the `@format` marker.
+
+Note that “in tandem” doesn’t mean “at the same time”. When the two options are used simultaneously, `--require-pragma` has priority, so `--insert-pragma` is ignored. The idea is that during an incremental adoption of Prettier in a big codebase, the developers participating in the transition process use `--insert-pragma` whereas `--require-pragma` is used by the rest of the team and automated tooling to process only files already transitioned. The feature has been inspired by Facebook’s [adoption strategy].
 
 | Default | CLI Override      | API Override           |
 | ------- | ----------------- | ---------------------- |
 | `false` | `--insert-pragma` | `insertPragma: <bool>` |
 
+[adoption strategy]: https://prettier.io/blog/2017/05/03/1.3.0.html#facebook-adoption-update
+
 ## Prose Wrap
 
 _First available in v1.8.2_