How to document an HTTP header - The MDN project 编辑

The MDN HTTP header reference documents HTTP header fields are components of the header section of request and response messages in the Hypertext Transfer Protocol (HTTP). They define the operating parameters of an HTTP transaction. This page explains how to create a new MDN reference page for an HTTP header.

Prerequisites

• You will need an MDN account.
• You will need to know or be able to dive into some HTTP.

Step 1 – find an HTTP header to document

• There are many HTTP headers defined in various IETF standards.
• IANA maintains a registry of headers and Wikipedia lists known header fields, but not all are relevant to web developers or part of an official standard.
• If there are red links on the current MDN header reference overview page, these headers are a good choice to document.
• If in doubt, ask an MDN contributor if you are unsure whether or not it makes sense to write about the header you have chosen.

Step 2 – look at existing header reference pages

• Existing HTTP headers are documented here.
• There are different header categories: General header, Request header, Response header and Entity header.
• Find the category the header you are about to document.
• Go to an existing header reference page that has the same category.

Step 3 – create a new page

• All header pages live under this tree: /docs/Web/HTTP/Headers/
• You can create a new subpage following this link.

Step 4 – write content

• Either use a copied structure from one of the existing HTTP header documents that you found in step 2 or start from scratch. It's your choice.
• Write about your new HTTP header.
• Make sure you have these sections:
  • Introduction text where the first sentence mentions the header name (bold) and summaries its purpose.
  • Information box containing at least the header type and if the header is a Forbidden header name
  • A syntax box containing all possible directives/parameters/values of the HTTP header.
  • A section that explains these directives/values
  • An example section that contains a practical use case for this header or shows where and how it occurs usually.
  • A specification section listing relevant RFC standard documents.
  • A "See also" section listing relevant resources.

Step 4a –  add tags to the page

• All HTTP header pages should at least have these tags: "HTTP", "Header", "Reference".

• If you have looked at other HTTP header pages, you will see that there is a macro that will fill in a browser table for you.
• The compatibility table page is generated from structured data. If you’d like to contribute to the data, please check out https://github.com/mdn/browser-compat-data/README.md and send us a pull request

Step 6 – add the header to the HTTP header list

• Make sure your header is listed in an appropriate category on the HTTP header reference overview page.

Step 7 – ask for review

• Use the editorial / technical review flags in the editing interface.
• Ask an MDN contributor for feedback. We will be happily helping you and celebrate the work you have done!

Step 8 – done

• All done! Woot!
• Why not let us know? Send us a tweet or get in touch!