Hi,
We are currently in the process of migrating the documentation for request version 1 ("legacy") from the library's README to the website. The goal of this migration is improve the documentation thanks to the possibility to structure and expand the current documentation: we have a whole website dedicated to documentation instead of a single file.

Objectives

Here are some concrete points I would like to focus on during the migration:

• API completeness: Dedicate a whole section for the API and make it exhaustive. request's API is much is larger than just the supported options. The module exports many functions (cookie, defaults, ...) and the returned values are often complex objects. Any object publicly accessible should be documented: the API documentation's completeness is a crucial for the guarantees offered by the semantic versioning of request.
• Examples: The original documentation has examples built around use cases (streaming, forms, etc.). These are good and we should keep them, but the API also needs examples. Ideally, each function or option should provide a few usage examples. These examples should be commented and runnable (do not assume any implicit context, most of times it just means that you should add the module importation).
• Types: Types provide information about the allowed values. Even if JavaScript is dynamically typed, having a clear definition of the type of a variable can help to complete the eventual vagueness in the english description (like the examples mentioned above). Since there is no standard syntax for this in Javascript, you can use some pseudo-code notation as long as it's clear. A recommended source of inspiration might be Typescript's notation. Try to render types as links to their description (see Node's documentation where types are clickable).
• Data relations: request defines some complex relations between it's objects. The function's signature can change the required options (.uri can be either provided as a function argument or as an option), there are some aliases, some flags control the effect other options (.useQuerystring), etc. In my opinion, these relations should be at least mentioned in the description of every implied object.
• External references: Every time request mentions an external resource, there should be a link. This link should be a permalink and ideally, you'd check that the target is archived on archive.org.

Related issues

• Create directory structure and entries in the summary
• Import the original documentation
• Add entries for all the public objects
• Add description for each public object
• Add examples for the module's main functions
• Update the main options documentation
• Check the features pages
• Fix the broken links (mainly around the the features pages ?), ensure that there is an archived version for the links
• Document missing types
• Solve TODOs remaining in the documentation
• TODO: Expand this list, open dedicated tickets to track progress, create a milestone ?

Contributing

While the legacy documentation is not ready to be published, work happens on the legacy-doc branch.
Make sure to choose this branch when submitting a Pull Request (PR).

Do not hesitate to comment here for general remarks or questions about the migration of the legacy documentation.

Previous discussions

• Legacy documentation #3