StackExchange / StackExchange/Stacks

Improve definitions and examples in the Grammar and mechanics guide regarding periods

Open
#1,029 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
672
Forks
107
Avg merge
2d 12h
Merged PRs (30d)
26

Description

Is your feature request related to a problem? Please describe.
The Grammar and mechanics guide contains a section on when to use periods: https://stackoverflow.design/content/guidelines/grammar-and-mechanics/#periods. It states:

Don’t use periods in interface copy unless it’s a full sentence or description.

However, the section does not contain a definition on what a "full sentence" is (or "complete sentence" as it is called in the examples in the section). This leads to, or at least does not address, meta questions on the usage of periods on SE.

Also, the examples provided in different parts of the guide seem inconsistent regarding period use. For example from Verbs and nouns, no period:

Log in to ask a question

Contrast with Hyphens (with period):

Start your free 14-day trial.

Get started. Sign up today.

Describe the solution you'd like
Add a definition of what a "full sentence" or "complete sentence" is (or what it is not). A useful difference seems to be an imperative phrase (do this) vs an indicative sentence, i.e., a "regular" sentence with at minimum a subject and a verb (Your account has been suspended.). Also choose between the two terms, either "full sentence" or "complete sentence" but not both.

The guide should also mention the difference between single phrases and combinations of two or more phrases, in which each phrase should end with a period, even if it is an imperative phrase.

Explicit examples for each case should be added in the Periods section, for the following cases:

  • imperative phrase
  • combination of two or more imperative phrases
  • complete sentence

Current incorrect examples should be changed, for example:

Start your free 14-day trial.

Your job listing was published on January 15

Additional context
This feature request was prompted by https://meta.stackexchange.com/questions/380566/make-full-stop-usage-consistent-in-badge-descriptions/380592.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Open the Grammar and mechanics guide and review the Periods section alongside Verbs and nouns and Hyphens. Update the terminology, guidance, and examples for imperative phrases, combinations of phrases, and complete sentences; done means the requested cases are covered consistently and the current incorrect examples are corrected.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
50/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.