Consistency in punctuation introducing lists

[janbrasna]

Code of Conduct

• [X] I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/contributing/style-guide-and-content-model/style-guide (and all usage)

What part(s) of the article would you like to see updated?

Rules for writing lists don't seem to include instructions for punctuation in the sentence preceding them. (The same might apply for preceding code samples, too — as the rule could equally be used for introducing the snippet that follows.)

There are several variations being used, even on this single page:

1. Colon (which seems most appropriate, easier to read, and is by definition "a punctuation mark used to precede a lists of items"…), e.g.:

• The secondary text should be capitalized as if it was the beginning of the line. For example:

  • foo: Something that provides bar.

• Use:

  • For an introduction to GitHub, see the following articles:

• For example, this is a first-party action:

  • [snippet]

• Code examples that use third-party actions must include the following disclaimer as part of the code block:

  • [snippet]

2. Period (ending the sentence naturally), used e.g.:

   • Each release note in a set describes one of the following changes.

     • Features

   • A release note for a feature answers the following questions.

     • Does this new functionality apply to me

   • The following documentation should reference "user accounts."

     • The "Enterprise administrator documentation" product

   • The table is generated with the following alignment syntax.

     • [snippet]

3. Nothing, e.g.:

   • At the end of the article containing MIT-licensed content

     • Create a header titled Legal notice

The first (":" colon) seems the easiest to read, making an explicit relation that the content/context continues on the following lines.

Not sure if a grammar definition or some style opinion specifies the usage of any of these; restricts or allows all. It just surprised me as a reader that often a sentence being demonstrated in a table, code or a list ends with a full stop.

Additional information

This is a meta issue. The inconsistency in the Style Guide is only an example, as the same can be observed around the site.

Using one page as an example:

1. Dependabot doesn't run Gradle but supports updates to the following files:

   • build

2. Dependabot supports version updates for GitHub Actions with the following caveats.

   • Dependabot only supports updates to GitHub Actions

3. Supported values

   • monday

If this is covered in the Style Guide, maybe that'd make a slightly more clear guidance how to use it in the articles, too.

[nguyenalex836]

@janbrasna Thank you for opening an issue! I'll get this triaged for review ✨

[subatoi]

Hi @janbrasna, and thanks for raising an issue—

There's a few things to note here. I agree with you, but with some qualifications :)

Where the GitHub style guide doesn't answer a question for us, we defer to the Microsoft Style guide, which for the case of introducing lists states:

Make sure the purpose of the list is clear. Introduce the list with a heading, a complete sentence, or a fragment that ends with a colon.

So by that definition, your third example ("nothing") is the one that's not conforming to any of the style guides we follow.

Generally speaking, we prioritise readability above all else and this is one of those cases where, whilst readability isn't compromised as such, it doesn't look great. It's probably also pertinent for me to comment that we don't have a linter rule to spot incomplete sentences, as sometimes they're actually helpful or by (correct) design.

In any case, if what I'm saying makes sense then I'd propose to alter this issue's scope accordingly. We'd happily accept PRs from you or any other user to fix such instances, but I'd kindly ask anyone to submit PRs that only affect a few files at a time, to make reviewing simpler and quicker and reduce any risk of merge conflicts (however small).

Thanks again: let me know what you think and I can add the help wanted label if you're in agreement.

[subatoi]

Hi @janbrasna 👋 just a gentle bump on this so we know how to take it forward 😄

[github-actions[bot]]

This issue has been automatically closed because there has been no response to our request for more information from the original author. With only the information that is currently in the issue, we don't have enough information to take action. Please reach out if you have or find the answers we need so that we can investigate further. See this blog post on bug reports and the importance of repro steps for more information about the kind of information that may be helpful.