How do you like the introduction?

[analog-nico]

Hey everyone who is watching! How do you like the extended introduction I just wrote?

The request ecosystem gets more diverse as we speak:

• request-promise joined in and gets its place in the documentation
• request@next will become highly configurable – especially considering the Basic API and the Chain API it will provide
• And request already provides two very distinct ways of using it: callbacks and streams

This all leaves us with a rather significant issue: New users must make some choices about how they want to use request.

IMHO the best way to break it down is:

1. How do I want to configure the request?
   • Via an options object (only option today, Basic API in the furture)
   • Via chaining (Chain API in the future)
2. How do I want to handle the response?
   • Via a callback
   • Via a promise
   • Via a stream

Since (1.) only becomes a choice to make once request@next is ready I wrote the new introduction showing a little about the options and then helping to decide whether to use callbacks/promises/streams.

Accordingly, I would structure the rest of the documentation in a way that the available options get its own chapter – because they apply equally to callbacks/promises/streams – and then a chapter for each of callbacks/promises/streams.

Let me know what you think before I proceed. Thanks!

[simov]

I like it!

Don't worry about the users, there will be always choices to be made. As long as all features (APIs) are separated and easy to maintain for us we're fine. Also I like the idea of having separate chapter for each option, lets see how it goes.

Just a reminder that the book gets build and published on every push to master, so in case you want to test something before that you can always build the book locally:

# install gitbook cli
npm install -g gitbook-cli
# install the latest version (stored in ~/.gitbook)
gitbook fetch
# optionally install plugins
gitbook install
# cd into your book's dir and generate it (_book folder)
gitbook build
# serve your book at http://localhost:4000
gitbook serve

[analog-nico]

Thank you @simov ! By "features" you are probably referring to what will become separate modules in request@next, right? I'll keep the structure you already drafted for "Authentication" and "Cookies".

Got to know these commands. Makes me like GitBooks more and more!