Skip to content
This repository was archived by the owner on Nov 6, 2023. It is now read-only.
This repository was archived by the owner on Nov 6, 2023. It is now read-only.

Split documentation into three categories #14579

Closed

Description

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).

Activity

  1. Bisaloo commented on Feb 10, 2018

    @Bisaloo
    Collaborator

    Relevant quote from a user in #14284 (comment):

    I guess I don't understand what the "rules" are, or what they do, how, or why I would write one. And the documention isn't sufficient for end-users. The FAQs go much too quickly into developer mode, in my opinion.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions