Navigation for legacy documentation

[demurgos]

We need to agree on an initial structure for the navigation/summary of the website, the goal is to at least approve the part relevant for the legacy documentation in order to assign separate tasks more effectively.

Previous propositions

• In february, Update site with pending information about Request #1 proposed the following structure for pending informations about Request:

  1. Home
     1.1. Quick examples so the user can choose which approach to take:
     1.1.1. Request with callbacks
     1.1.2. Request-Promise with promises
     1.1.3. Request with streams
  2. Use Cases similar to those in the Request-Promise cheat sheet
     2.1. Common use cases with callback-based and promise-based code maybe side by side
     2.2. Streaming use cases
  3. Documentation
     3.1 Full API documentation in the style of the current Request README
  4. Support / Contribute
     4.1. Link to Gitter chat
     4.2. Link to repos, contribution guidelines
     4.3. Link to Request architecture docs etc.

  Implicitly, it documents a single version of Request (when we have to also prepare some place for the next version). This is a good structure in my opinion. Use cases could be expanded to include the ones detailed in the library's README.md (forms, proxies, authentication, etc.).

• In Legacy documentation #3, I started to import the legacy API from the library's repo to the website. It was for me the occasion to to reflect on the navigation with a bigger focus on the API. My idea is to document every publicly accessible object in its own page. I differentiated three kinds of objects:

  The main module is the object you import in your code (for example with
  require('request')). It is the entry point for Request's API and exposes most
  of this package's features.

  Some functions return objects with methods, they are described in the
  "classes" section. You should not instanciate them yourself.

  Properties of simple container objects (such as options) are documented as
  interfaces.

  "class" and "interface" might have a disputable meaning in the context of JavaScript, but I feel that it express well the "abstract" semantics of those objects (and the semantics seem more important than the actual implementation details such as prototypal inheritance).

  Given that, here is a screenshot of the summary I use in the meantime to work on the API:

  

  The API part itself is not structured because I couldn't find any satisfying way to make it fit into the "book summary" structure (hierarchy and ordered elements), but it seems to be good enough thanks to the relatively small number of elements.

Proposition

If we try to combine the best of those summaries, here is what I propose:

• Home: Main page, with the logo, a short description and links to the repositories, the most important part of the documentation and other relevant URIs.
• Introduction: Longer description of Request (why would you want to use it ? what are its limits ? a bit of history, maybe). I separated it from Home because I feel that major navigation links and the library description should not be in the same place. This may be a mistake since I might be thinking more in a "website" way than a "book" way.
• Which version should I use ?: Since the website documents both the "legacy" and "next" versions, we should have a visible section clarifying the difference between both versions. This difference should be reminded in the sections for each version.
• Request legacy: Or maybe simply "Request v1" ? "legacy" sounds like a cool internal name, but it might be confusing, especially since it is still supported (right ?). legacy is not as bad as deprecated but has some "warning" connotation. This section would be the home page for the documentation of the currently stable version.
  • Getting started: Should include three ways to use Request listed by @jabrena: callbacks, promises and streams.
  • Use cases: or "features" ? A simple index page for pages focusing on a library's feature. Here are some examples (most of them are imported from the library's repo).
    • Authentication: ping @simov
    • Cookies: ping @lalitkapoor
    • Custom HTTP headers
    • Debugging
    • Forms
    • HTTP Authentication: see Authentication ?
    • OAuth signing
    • Proxies
    • Streaming
    • HAR
    • Timeouts
    • TLS/SSL
    • UNIX domain sockets
    • Promises
  • API: overview of the API, definitions for the concepts used across the API (the above quote about interfaces and classes comes from here).
    • Main module: Entry point of the library
    • RequestOptions: 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.
    • 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.
    • ...
• Request Next: TODO
• Request Promises: TODO
• Contact: support and contribution links (most of them should already be on the homepage I think)

Conclusion

This is a pretty lengthy issue but we need to tackle this pretty early so we get a good view of what we actually want. It would be nice to get some feedback.

[analog-nico]

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?

[demurgos]

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.