Comments (2)
Hi @demurgos , I like your objectives listed in #4 !
Let me add two objectives that lead me to the navigation proposal below:
- 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.
- 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. - ...
- Options merging: Explains what is the actual configuration if you chain multiple
- 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?
from request.js.org.
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.
from request.js.org.
Related Issues (5)
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from request.js.org.