You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Nov 6, 2023. It is now read-only.
Repository navigation
This repository was archived by the owner on Nov 6, 2023. It is now read-only.
Discussion: use Google styleguide for Markdown documents #14467
The motivation is that in pull request #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.
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.
@sampablokuper I agree with you in both cases that the wording is unclear. However, to address your point at #14423 (comment):
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 (#10724) and licensing (#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.
@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.
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.
Reacted by CHAN, Chak Shing, Hugo Gruson, Jeremy Nation and Kate Chapman
@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.
Since @Hainish agreed with this and no one seems opposed, I consider this adopted. I'm moving forward with PR #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.
Activity
jeremyn commentedon Jan 29, 2018
@sampablokuper made these points in #14423 (comment):
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.
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.
jeremyn commentedon Jan 30, 2018
@sampablokuper I agree with you in both cases that the wording is unclear. However, to address your point at #14423 (comment):
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 (#10724) and licensing (#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.
jeremyn commentedon Jan 31, 2018
@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.
Hainish commentedon Jan 31, 2018
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.jeremyn commentedon Jan 31, 2018
@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
masterbut in this case is calledgh-pages.jeremyn commentedon Feb 5, 2018
Since @Hainish agreed with this and no one seems opposed, I consider this adopted. I'm moving forward with PR #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 commentedon Feb 8, 2018
@Hainish Can you suggest where we should mention this styleguide for contributors?
Hainish commentedon Feb 9, 2018
@jeremyn I agree with you. Probably a line or two in a separate section between
Contributing CodeandContributing Translations. Thanks!jeremyn commentedon Feb 9, 2018
PR #14467 adds a "Contributing Documentation" section.
jeremyn commentedon Feb 9, 2018
I'm closing this issue since we have adopted the Google style guide and updated
CONTRIBUTING.md. Thanks everyone.