Split documentation into three categories #14579

Type: other

At present, and for the foreseeable future, it seems likely that any given piece of https-everywhere documentation will be intended for one of these three audiences:

1. end users (e.g. "What if HTTPS Everywhere breaks some site that I use?"; "How do I get rid of/move the HTTPS Everywhere button in the toolbar?"; etc.);
2. webmasters (e.g. "Isn't it more expensive or slower for a site to support HTTPS compared to regular HTTP?"; "How do I add my own site to HTTPS Everywhere?"; "How to Deploy HTTPS Correctly"; etc.);
3. developers, including ruleset contributors, i.e. anyone aiming to submit a patch or a pull request (e.g. CONTRIBUTING.md; README.md; ruleset-testing.md; development.md; rulesets.md; and perhaps others).

I propose that:

1. with the exception of README.md and the file rendered as https://www.eff.org/https-everywhere , each documentation file should clearly state which of those three audiences it is intended for; and in particular,

2. with the exception of README.md and the file rendered as https://www.eff.org/https-everywhere , all documentation intended for end users should be consolidated into one file, structured roughly as follows:

   # HTTPS Everywhere user guide
   ## About
   (Short description here, tailored to end users.)
   ## Installation
   (Installation instructions.)
   ## Uninstallation
   (Removal instructions.)
   ## FAQ
   (End-user FAQ items only.)
   

3. with the exception of README.md and the file rendered as https://www.eff.org/https-everywhere , all documentation intended for webmasters should be consolidated into one file, structured roughly as follows:

   # HTTPS Everywhere webmaster guide
   ## About
   (Short description here, tailored to webmasters.)
   ## How to deploy HTTPS correctly
   (HTTPS deployment instructions.)
   ## FAQ
   (Webmaster FAQ items only.)
   

4. with the exception of README.md and the file rendered as https://www.eff.org/https-everywhere , all documentation intended for developers should be consolidated into a smaller set of files than is the case at present, and that one of these files should have an FAQ section where questions like "What happens if I create a ghost PR?" can be answered;

5. README.md and the file rendered as https://www.eff.org/https-everywhere should be structured similarly to each other (and should perhaps even be the same underlying file), and each of them should, as their sole purposes, (a) help readers to identify themselves, in that moment, as either an end-user, a webmaster, or a developer, and (b) link readers to the corresponding documentation (as described above).