openwebdocs
OWD project: Update HTTP docs (HTTP/2, HTTP/3, CSP, etc)
This proposes that we work update HTTP documentation on MDN docs to take into account the HTTP/2 & HTTP/3 protocols, a move to Markdown, fix the outstanding issues, and revisions of the unclear areas (CSP, Cache…)
Problem statement
MDN docs articles about HTTP are now several years old. This area overall structure and content are still mostly in good shape and new features that appeared over the years (like Client-Hints for example) were added mostly smoothfully in that structure.
But HTTP has evolved over the years: HTTP/2 is now the most common version in use and HTTP/3 is in the progress of being released. We don't speak about these versions at all and that 1) leave our readers in the vague about these versions 2) makes MDN docs look outdated. We don't need to speak in all details about these protocols – a web dev doesn't need them – but we need at least:
- An introduction for each of these two protocols;
- Up-to-date glossaries entries for them, but also related technologies like QUIC;
- Guide about advanced features and how to use them (Push functionalities?)
Also MDN docs get quite regularly issues about HTTP; there is currently a back-log of 23 issues, about 5% of the overall total, some of them pretty complex to solve.
HTTP docs, like the others area of MDN docs, have to move to Markdown as the devs won't want to keep it in HTML for long. There is a need edit consequently this area of the docs.
Priority assessment
This table checks this project against the OWD prioritization criteria.
| Criteria | Assessment |
|---|---|
| Effort | Medium. We will write about 5-10 new articles overall, most of them (once HTTP/3 ships) low maintenance. There may be some untangling of complex articles and some revisions of the other articles (are the types of headers correctly set?). The whole area is 292 pages that will need to be reviewed and edited (but not completely rewritten) |
| Dependencies | No dependencies on the devs. A little bit of support for the migration to Markdown |
| Community enablement | Low, though updating templates may help our community to update it regularly. |
| Momentum | HTTP/3 has been released by default in several browsers, but not yet all. Having up-to-date docs when people look for novelty is always good. |
| Enabling learners | Only basic understanding of HTTP/3 will be provided |
| Enabling professionals | N/A |
| Underrepresented topics / ethical web | N/A |
| Operational necessities | The move to Markdown will have to happen anyway. |
| Addressing needs of the Web industry | N/A |
Task list
- Assess in details the HTTP area and make a proposal of new pages to be written, structural to be made.
- Process with the minor restructuration
- Add the 5-10 new articles
- Update the area by resolving the HTTP-related issues on github.
- Prepare for the Markdown migration (can be done in parallel with the other activities)
- Migrate to Markdown
- Review and fix details.
More information
Open Web Docs (OWD) is a non-profit collective funded by corporate and individual donations.
In order for this project to happen, please consider donating to OWD on https://opencollective.com/open-web-docs. For more information on sponsorship and membership tiers, see https://openwebdocs.org/membership/
More information is available at https://openwebdocs.org. For questions, please reach out to [email protected].
I'm happy to help with some of this at your direction - don't feel sufficiently well informed yet on HTTP to lead it. One thing that occurs to me is that there are some headers that aren't relevant/drop in different versions. As most of them are relevant, we probably need a more systematic and obvious way of highlighting the ones that are not by HTTP version.
Here is the draft plan for documenting HTTP/2 on MDN. Everybody, please review and add comments to it.
Once the review process is over, I will post the task list in this Github issue (and execute the plan).
@mnot, @mcmanus, @reschke, @jasnell: you all have been referred to me as Subject Matter Experts (SME) by our members, and even if I have already interacted, and met, with some of you, I feel a bit intimidated.
I would be highly grateful if you would take some of your time to review the document, and I hope it is short enough. Having a 6-page introduction to HTTP/2 on MDN, trusted by many web developers, would help increase the overall knowledge about this protocol (and about HTTP/3 afterward) among people using it transparently every day.
Thank you in advance for your time, and feel free to comment in the document, or here, or to ask any question.