[suggestion] Move README.md to FAQ.md

[schnittstabil]

Knowing why the interfaces are the way they are is worth reading – however, only for potential contributors, not potential consumers.

The README.md is displayed at packagist.org/…/http-middleware and github. In my opinion, potential consumers will be deterred by the discussion about the pros and cons of the chosen design.

Personally, I think readmes should be as short and concise as possible. They should be optimally designed and completely dedicated to customer needs, e.g.:

1. The namespace should be the title: # Interop\Http\Middleware.
2. A small prelude, which states
   • this packages provides the official interfaces of the PSR-15
   • PSR-15 is a proposal and is still undergoing changes
3. A tiny # Install section:

   composer require http-interop/http-middleware

4. A # Usage section: a tiny code snippet, which
   • is easy to understand
   • also contains namespace stuff: use Interop\Http\Middleware\ServerMiddlewareInterface; etc.
   • can be easily copied and modified by potential consumers
5. A small description of the API – maybe in this case just the interface code including its docblocks.
6. Refer to the current readme as FAQ.md
7. Optionally mentioning contributors (consumers may want to contact you)
8. A tiny # License section:

   MIT © PHP-FIG

@shadowhand: I'm willing to create a PR for that.

[shadowhand]

This probably makes sense. Replacing the README with META might not be ideal in the long term.

Any objections @http-interop/http-middleware-contributors ?

[shadowhand]

README has been removed and points to FIG for documentation.