README.md

textlint-rule-preset-google

Google Developer Documentation Style Guide for textlint.

Install

Install with npm:

npm install @textlint-rule/textlint-rule-preset-google

Usage

Via .textlintrc(Recommended)

{
    "rules": {
        "@textlint-rule/preset-google": true
    }
}

Via CLI

textlint --rule preset-google README.md

Rules

Remember that everything in this guide is a guideline, not a draconian rule.

• Introduction
• About this guide
• Style-guide highlights
• General principles
• Style and tone
  • Some things to avoid where possible
    • Placeholder phrases like "please note" and "at this time."
    • Starting all sentences with the same phrase (such as "You can" or "Todo").
    • Phrasing in terms of "let's" do something.
    • Using phrases like "simply" or "It's that simple" or "It's easy" in a
    • procedure, unless it's an extraordinarily simple/easy procedure.
  • Politeness and use of "please"
    • ✔️ textlint-rule-google-tone
• Documenting future features
• Accessible content
• Writing for a global audience
  • ✔️ textlint-rule-google-contractions
  • Avoid misplaced modifiers.
• Language and grammar
• Abbreviations
  • ✔️ textlint-rule-google-abbreviations
  • Prefer English terms over Latin abbreviations. Don't use "i.e." or "e.g.";
    • instead, use "that is" or "for example," respectively.
  • Periods with abbreviations
• Active voice
  • use active voice instead of passive voice
• Anthropomorphism
• Articles (a, an, the)
  • ✔️ textlint-rule-google-articles
  • a/an = indefinite article
  • the = definite article
• Capitalization
  • ✔️ textlint-rule-google-capitalization
  • Capitalization in titles and headings
  • Capitalization and colons
  • Capitalization and figures
  • Capitalization and hyphenated words
  • Capitalization in lists
  • Capitalization for tables in text
• Clause order
  • ✔️ textlint-rule-google-clause-order
  • For more details
  • To ~, instruction
• Contractions
  • ✔️ textlint-rule-google-contractions
  • Noun+verb contractions
  • Don't use double contractions
• Cross-references
• Plurals in parentheses
  • ✔️ textlint-rule-google-plurals-parentheses
  • Don't put optional plurals in parentheses.
• Prepositions
• Present tense
  • will
  • would
• Pronouns
  • Gender-neutral pronouns
  • Personal pronouns/Second Person
• Second person
  • Use "you" rather than "we."
• Spelling
• Verb forms in reference documentation
  • Use "does" rather than "do" in a specification
• Word list
  • ✔️ textlint-rule-google-word-list
  • Word list
• Punctuation
• Apostrophes (possessives)
  • ✔️ textlint-rule-google-possessives
  • incorrect possessives
• Colons
  • ✔️ textlint-rule-google-colons
  • Introductory phrase preceding colon
  • Bold text preceding colon
  • In general, the first word in the text that follows a colon should be in lowercase.
• Commas
  • Serial commas
  • Commas after introductory words and phrases
  • Commas separating two independent clauses
  • Commas separating independent from dependent clauses
  • Setting off other kinds of clauses
• Dashes
  • ✔️ textlint-rule-google-dashes
  • use — insteadof -
  • Colons instead of dashes in lists
• Ellipses
  • ✔️ textlint-rule-google-ellipses
  • Use quoted text
  • Punctuation and spacing
• Exclamation points
  • ✔️ textlint-rule-google-possessives
  • Don't use ! and ?
• Hyphens
  • ✔️ textlint-rule-google-hyphens
  • Don't hyphenate adverbs ending in "ly"
  • Don't add words such as -from- or -between-.
• Parentheses
• Periods
  • Periods with lists
  • Periods with URLs
    • Avoid put a space URLs and period
  • Periods with quotation marks
  • Periods with parentheses
  • Periods with headings
  • Periods with numbers
  • Periods with captions
  • Periods with abbreviations
• Pluralizing a single letter
• Quotation marks
  • ✔️ textlint-rule-google-quotation-marks
  • American Style
  • Single quotation marks
• Semicolons
• Slashes
  • ✔️ textlint-rule-google-slashes
  • Slashes with dates
  • Slashes with file paths and URLs
  • Slashes with alternatives
  • Slashes with fractions
  • Slashes with abbreviations
• Formatting and organization
• Dates and times
• Figures and other images
• Headings and titles
  • Capitalization
• Lists
• Notes and other notices
• Numbers
• Phone numbers
• Procedures
• Spaces between sentences
  • ✔️ textlint-rule-google-sentence-spacing
  • Leave only one space between sentences
• Tables
• Units of measurement
  • ✔️ textlint-rule-google-units-of-measure
  • Formatting units of measurement
• Computer interfaces
• API reference code comments
• Code in text
• Code samples
• Documenting command-line syntax
• Linking to other sites
• UI elements and interaction
• HTML and CSS
• Fonts and font size
• HTML and semantic tagging
• HTML formatting
• Link text
• Making headings into link targets
• Markdown versus HTML
• URLs in img elements
• URLs in links
• Names and naming
• Example domains and names
• File names
• Product names
• Trademarks
• Other
• Other editorial resources
• Release notes

Changelog

See Releases page.

Running tests

This monorepo use Yarn.

Install dependencies and Run npm test:

yarn install
yarn bootstrap
yarn test

Contributing

For bugs and feature requests, please create an issue.

Pull requests and stars are always welcome.

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request :D

Adding new rule

1. Create pacakges/textlint-rule-<rule-name>
   • Rule name is based on style guide URL
   • For example, https://developers.google.com/style/clause-order's rule name is clause-order
2. Setup package using textlint-scripts.
3. Write rule
4. Test rule
5. Submit Pull Request!

Author

• github/azu
• twitter/azu_re

License

MIT © azu