Activity

1. demurgos

   added

   legacy

   on Sep 28, 2016
2. analog-nico commented on Oct 3, 2016

   

   analog-nico

   on Oct 3, 2016

   Member

   More actions

   Hi @demurgos , I like your objectives listed in #4 !

   Let me add two objectives that lead me to the navigation proposal below:

   1. We have many ways HOW to use Request/Request-Promise: Callbacks, Promises, Streams plus legacy/next. But whichever flavor your prefer most of the things stay the same – e.g. the options. Especially because I am the maintainer of Request-Promise I am motivated to find a navigation that allows us to document the overlapping parts just once.
   2. A new user faces a quite steep learning curve because Request offers so many features/options. The docs should allow the user to quickly navigate to the parts that are relevant without having to read the whole book.

   With both objectives in mind I wrote the Getting Started page. It starts with two examples to give a quick picture of the lib and then helps the user to decide which flavor to use – callbacks, promises, or streams. IMO this is the most important decision for a new user to make.

   In regards to the decision whether to use legacy or next I would assume that the next version will be recommended and no reason will exist to use legacy other than being stuck with the old version in an old project. So here I would rather write the whole docs for legacy right now. And later – once next becomes available – branch the whole book so people may still access the legacy docs. In the proposal below I assume you agree. Otherwise I will update it.

   As you can see on the Getting Started page I already added some links to the end of each "flavor" section that shall allow the user to jump to the parts of the book that are relevant given the chosen flavor – without having to read the whole rest of the book.

   So combining your navigation above with the additional objectives I would propose:

   • Home: Fairly done.
   • Getting Started: Fairly done, too. I think it matches well with the introduction you proposed above. Maybe we should add a little bit of text to the page that answers e.g. "What are its limits?". However, I wouldn't add too much – like a bit of history – because people soon get into tl;dr mode.
   • Use Cases: Most users think more in terms of what they wanna do. Especially we maintainers think in features. Thus I would combine the best of both worlds: Request-Promise's cheat sheet and the feature list from above minus promises and streams because all examples shall cover all flavors:
     • Crawling Webpages
     • Calling REST APIs
     • Sending Form Data
     • Authenticated Requests (includes OAuth signing)
     • Caching Requests with ETags (not a feature of Request but a common use case)
     • Cookie Handling
     • Custom HTTP Headers
     • Debugging
     • Error Handling (e.g. listing error types like ENOTFOUND)
     • HAR Support
     • Optimizing Parallel Requests (tips to configure the HttpAgent etc.)
     • Retrying Requests (not a feature of Request but a common use case)
     • Proxied Requests
     • Secure Requests
     • Testing with Mocks (the use of different mock libraries that emulate the http requests)
     • Timeouts / Cancelation
     • UNIX Domain Sockets
   • Flavors:
     • Callbacks: Linked from the Getting Started page and explains basic boilerplate plus the callback signature/parameters/behavior
     • Promises: Linked from the Getting Started page and again explains basic boilerplate plus use with async etc. I will write that of course.
     • Streams: Same thing – boilerplate, special behaviors, and must-knows.
   • API: overview of the API, definitions for the concepts used across the API (the above quote about interfaces and classes comes from here). – Copied from above. I suggest each page explains everything for the callbacks flavor by default and has additional paragraphs at the bottom that point out differences when using the other flavors.
     • Main module: Entry point of the library
     • RequestOptions: Linked from the Getting Started page; Interface the options used in the main functions and request.defaults(...)
     • Request: The return value of the main functions is an instance of the Request class. This one is tricky, looks like the available attributes evolve in the time (but we'll deal with it in another issue).
     • ...: You get the idea, any publicly accessible object is described
   • Advanced concepts: This would be a place for complex examples involving multiple features or technical points requiring a longer description. – Copied from above
     • Options merging: Explains what is the actual configuration if you chain multiple request.defaults() and then call one of the main functions with an options object.
     • ...
   • Contact: support and contribution links (most of them should already be on the homepage I think) – Copied from above

   Since we always have the three flavors to manage, I have one suggestion for the code examples: There is a GitBook plugin "codetabs" that would allow us to provide the code snippets for all flavors:

   

   We would use "Callbacks", "Promises", "Streams" and always start with providing the callbacks example. I'll add the promises examples and whenever it makes sense we would lazily add the streams example. So it is not much extra work but allows us to easily have one navigation structure for all flavors combined.

   Big question now before we discuss the details: Should the navigation structure omit the legacy/next distinction and we branch the whole book when next becomes available or should we design legacy/next into the navigation structure?
3. demurgos commented on Oct 13, 2016

   

   demurgos

   on Oct 13, 2016

   MemberAuthor

   More actions

   Hi,
   Sorry the long delay. I really like the idea about combining the snippets for the different "flavors" of the Request API. I did not look how to add plugins but it would be great to have this.

   In regards to the decision whether to use legacy or next I would assume that the next version will be recommended and no reason will exist to use legacy other than being stuck with the old version in an old project. So here I would rather write the whole docs for legacy right now. And later – once next becomes available – branch the whole book so people may still access the legacy docs. In the proposal below I assume you agree. Otherwise I will update it.

   After some reflection, I agree with you: this is the best way to keep it clear: this should only document the legacy version. So to answer your big question: we should omit the distinction until next is ready.