Https-everywhere: Discussion: use Google styleguide for Markdown documents

[jeremyn]

Type: other

(Ping @brainwane @gloomy-ghost @Hainish @J0WI @wonderchook but this discussion is open to anyone.)

I'm proposing that we adopt the Google styleguide for Markdown documents such as CONTRIBUTING.md and README.md.

The motivation is that in pull request https://github.com/EFForg/https-everywhere/pull/14423 , @sampablokuper proposed hard wrapping our Markdown documents to 80 characters per line. This resulted in an unproductive discussion debating the merits of soft- vs hard-wrapping, particularly related to computer accessibility. I would like to prevent these discussions in the future, and take maintainers out of the role of judging Markdown style, by fully adopting a styleguide from some large organization that has presumably considered accessibility and other factors.

If we go with this, we don't need to update all our documents right away. The idea is simply to arrange things so that style updates that align with the styleguide can be merged without discussion, and similarly style updates that go against the styleguide can be rejected without discussion.

What I want from this issue is:

• For EFF staff ( @Hainish ) to specifically agree to support this proposal, and
• To give people in the community a chance to discuss it

Assuming the EFF supports this proposal, and no one argues against it for a week or so, we should consider it adopted.

I'm open to using the styleguide from another organization if people want to avoid Google for ethical/political reasons.

In this discussion, please avoid arguing based on aesthetic or trivial preferences. Also, I want to avoid a piecemeal styleguide, such as starting with Google's and making modifications. The point here is to remove discretion to debate trivial differences, but if we have some custom styleguide then I think it will make things worse in that respect.

[jeremyn]

@sampablokuper made these points in https://github.com/EFForg/https-everywhere/pull/14423#issuecomment-361125026:

At a glance, Google's Markdown style guide looks broadly reasonable. I think it would be a good starting point. I wouldn't necessarily adopt it wholesale.

For instance, it does have at least one stipulation that I balked at: "Wherever possible, shorten your links." I think the EFF will agree ([1], [2]) that URL shorteners threaten privacy and should be treated with caution.

The "shorten your links" quote is in the Links section. I think don't think this means you should use URL shorteners like https://bitly.com/ or https://goo.gl/ , which I also don't like, but instead means you should remove extra fluff from regular URLs like reference codes, encoding etc where possible. Google search URLs often have a lot of this fluff, for instance. So I don't think this is a problem.

Also, it only explicitly mentions 80 character wrapping in the "Links" section, which is a bit odd.

The Character line limit section says you should "wrap your text", and the Links sections refers to "the 80 character wrapping". It is not totally explicit but I think together this implies all text should be hard wrapped to 80 characters where reasonable.

[ghost]

@jeremyn wrote:

@sampablokuper made these points in #14423 (comment):

At a glance, Google's Markdown style guide looks broadly reasonable. I think it would be a good starting point. I wouldn't necessarily adopt it wholesale.

For instance, it does have at least one stipulation that I balked at: "Wherever possible, shorten your links." I think the EFF will agree ([1], [2]) that URL shorteners threaten privacy and should be treated with caution.

The "shorten your links" quote is in the Links section. I think don't think this means you should use URL shorteners like https://bitly.com/ or https://goo.gl/ , which I also don't like, but instead means you should remove extra fluff from regular URLs like reference codes, encoding etc where possible. Google search URLs often have a lot of this fluff, for instance. So I don't think this is a problem.

It's ambiguous and could mean either, or both. A good style guide should be clear. So, that part should be improved if the Google style guide is used as a basis.

Also, it only explicitly mentions 80 character wrapping in the "Links" section, which is a bit odd.

The Character line limit section says you should "wrap your text", and the Links sections refers to "the 80 character wrapping". It is not totally explicit but I think together this implies all text should be hard wrapped to 80 characters where reasonable.

Explicit is better than implicit, especially in a style guide :) So, again, that part should be improved if the Google style guide is used as a basis.

[jeremyn]

@sampablokuper I agree with you in both cases that the wording is unclear. However, to address your point at https://github.com/EFForg/https-everywhere/pull/14423#issuecomment-361125026:

If you open a discussion, as you proposed above, then hopefully these and any other issues with that style guide can be addressed, and the EFF will then end up with its own Markdown style guide, which will be a close derivative of the Google one but better organised and more privacy-conscious.

I simply don't think the EFF has the resources to create and maintain a full styleguide for Markdown documents. They don't maintain any other public styleguides. There are also open discussions related to a code of conduct (https://github.com/EFForg/https-everywhere/issues/10724) and licensing (https://github.com/EFForg/https-everywhere/pull/13062) that have not been resolved. The EFF does not have a good track record at efficiently creating project- or organization-wide standards documentation.

The only way this will realistically happen is if we adopt some other public styleguide in its entirely. Attempting to create our own styleguide, even using another styleguide as a base, means this issue will die in committee. That's just how it is, unfortunately.

[ghost]

@jeremyn wrote:

I agree with you in both cases that the wording is unclear.

Thanks - glad it's not just me :)

They don't maintain any other public styleguides.

That isn't strictly true ;)

I simply don't think the EFF has the resources to create and maintain a full styleguide for Markdown documents. ... The only way this will realistically happen is if we adopt some other public styleguide in its entirely [sic]. Attempting to create our own styleguide, even using another styleguide as a base, means this issue will die in committee.

I think it would be fair for the EFF to adopt the Google Markdown style guide, for all of those reasons. I hope you think it would be fair for me or anyone else to file PRs against whichever style guide is adopted, if we have concrete improvements to propose.

If you don't think it would be fair for anyone to open PRs against the style guide, then please let's adopt one of these instead, about which I currently have no qualms:

• https://github.com/carwin/markdown-styleguide (which is concise); or
• the Markdown Style Guide wrap:no, list-marker:hyphen, code:fenced (which is comprehensive).

[jeremyn]

@sampablokuper The ruleset style guide that you linked is uniquely important to this project and cannot be outsourced.

My proposal assumes that if we adopt the Google styleguide, we will follow the main branch of it and will track their changes. You could file whatever PR against it that you like, that's between you and Google.

The motivation for this proposal was to avoid arguments about accessibility by adopting a styleguide from a major organization that has presumably thought about that subject carefully. We want to benefit from the enormous work their legal, personnel, and usability departments have done for their own staff. The two guides you link don't have that advantage.

[ghost]

My proposal assumes that if we adopt the Google styleguide, we will follow the main branch of it and will track their changes. You could file whatever PR against it that you like, that's between you and Google.

Fair enough :)

But I hope you will reconsider this part of your proposal if Google ever modifies its style guide to say something equivalent to, "All links should be shortened with goo.gl (so that we can surveil you and your users)."

a major organization that has presumably thought about that subject carefully

That such thinking would trickle down to their Markdown style guide is quite a big presumption ;) Anyway, I take your point. Thank you for clarifying this part of your reasoning :)

[Hainish]

I'm fine with adopting Google's style guide. One additional advantage is that by choosing a largely adopted style guide, it's more likely that a linter (such as markdownlint) will include the conventions of that style, and we can build this into our CI or generate automated feedback.

[ghost]

@sairamananonly The style guide link goes to the specific commit so it will never change.

[jeremyn]

@epicminecrafting I generally link to specific commits, instead of branches, so that future readers know the specific thing I was referring to when I made a comment. However my intention with this proposal is that we follow Google's main branch, which is usually called master but in this case is called gh-pages.

[jeremyn]

Since @Hainish agreed with this and no one seems opposed, I consider this adopted. I'm moving forward with PR https://github.com/EFForg/https-everywhere/pull/14423 to introduce hard line wraps. We should probably also mention the styleguide in CONTRIBUTING.md, just a sentence or two in a new "Contributing Documentation" section.

[jeremyn]

@Hainish Can you suggest where we should mention this styleguide for contributors?

[Hainish]

@jeremyn I agree with you. Probably a line or two in a separate section between Contributing Code and Contributing Translations. Thanks!

[jeremyn]

PR https://github.com/EFForg/https-everywhere/issues/14467 adds a "Contributing Documentation" section.

[jeremyn]

I'm closing this issue since we have adopted the Google style guide and updated CONTRIBUTING.md. Thanks everyone.