-
Notifications
You must be signed in to change notification settings - Fork 151
Rubric
As we review articles, tutorials, and reference materials, we should use this as a guide to assess consistent quality across the docs. Please add as necessary.
true constants should be declared with all-caps, snake-case names
example: const BUCKET_NAME = "my-bucket"
Kenton pointed out that many uses struggle when modifying requests/responses and forget to copy over obscure but important properties. Best practices for partial overwrites are also inconsistent with different properties (i.e. only overwriting certain headers, not stomping on redirect options). It's likely worth its own short article, but here's some links for the moment to guide your code examples:
https://stackoverflow.com/questions/54319675/pass-redirect-through-to-visitor/54334947#54334947
https://github.com/whatwg/fetch/issues/671 (a proposal for improved request/response rewriting outlining the ergonomic issues).
While MDN keeps exhaustive, user-friendly documentation of nearly all of the web specifications that are relevant to us, we do not pin to their documents, but to the living specifications themselves. Also, we don't necessarily implement the entire surface area of every API we offer in the Workers runtime, so it is important to be explicit with our documentation and how we link to the MDN documents.
For example, we implement the entire surface of the Headers object in the Fetch API, with one caveat. In that case, it is appropriate to call out the caveat on our page, then link to the Headers page on MDN.
However, we do not implement the entire surface area of either Response or Request; in this case, we should not only call out any caveats, we should enumerate the methods and properties that we do implement and link directly to those definitions, rather than the top level Request or Response page.
Whenever possible, refer to the code uploaded by users as "apps", "serverless functions", or "scripts" rather than "workers". The latter is relatively overloaded and can cause confusion. We refer to our platform as "Cloudflare Workers", for example "deploying your app to Cloudflare Workers".
prefer the imperative voice in reference definitions
Avoid use of the "10% of all HTTPS traffic" stat; it is being phased out.