Skip to content

📝 Docs: Style guide for headings, content, etc. #5446

@mark-wiemer

Description

@mark-wiemer

Documentation Request Checklist

Overview

We should start a brief style guide to make the site's copy more consistent. This will make it easier to read and understand for our users :)

  • Headings: sentence case? Title Case? I prefer sentence case as it's less ambiguous. In Title Case, do you capitalize "Into"?
  • "Explainers" heading style: Present tense or imperative? e.g. "Finding global leaks" or "Find global leaks"
  • Other thoughts? We do have an inclusive language checker already to remove mentions of "simply" or "just" (ref .eleventy.js)
  eleventyConfig.addPlugin(
    require('@11ty/eleventy-plugin-inclusive-language'),
    {
      words:
        'simply,obviously,basically,of course,clearly,everyone knows,however,easy'
    }
  );

Acceptance criteria: concise maintainer-focused document with "good" and "bad" examples for each rule. Does not need to be comprehensive, but should reduce decision fatigue and be referenced in PR reviews as needed

Additional Info

No response

Metadata

Metadata

Assignees

Labels

area: documentationanything involving docs or mochajs.orgcore-teamissues which must be handled by Mocha's core teamstatus: accepting prsMocha can use your help with this one!

Type

No type
No fields configured for issues without a type.

Projects

Status
Backlog

Relationships

None yet

Development

No branches or pull requests

Issue actions