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.

Discussion: use Google styleguide for Markdown documents #14467

Closed

Description

@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 #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.

Activity

  1. jeremyn commented on Jan 29, 2018

    @jeremyn
    ContributorAuthor

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

    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.

  2. jeremyn commented on Jan 30, 2018

    @jeremyn
    ContributorAuthor

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

  3. jeremyn commented on Jan 31, 2018

    @jeremyn
    ContributorAuthor

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

  4. Hainish commented on Jan 31, 2018

    @Hainish
    Member

    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.

  5. jeremyn commented on Jan 31, 2018

    @jeremyn
    ContributorAuthor

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

  6. jeremyn commented on Feb 5, 2018

    @jeremyn
    ContributorAuthor

    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.

  7. jeremyn commented on Feb 8, 2018

    @jeremyn
    ContributorAuthor

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

  8. Hainish commented on Feb 9, 2018

    @Hainish
    Member

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

  9. jeremyn commented on Feb 9, 2018

    @jeremyn
    ContributorAuthor

    PR #14467 adds a "Contributing Documentation" section.

  10. jeremyn commented on Feb 9, 2018

    @jeremyn
    ContributorAuthor

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

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

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions