House Style

Maintain the style guide

This topic is for style guide owners. The style guide is a Flare project. Your team's rules are in Content/Resources/StyleGuide/Company. Google's rules come with House Style. Don't copy or edit them: change them from your Company folder.

To set up a guide for a team, see Set up a team style guide.

Write rules

The About this style guide topic in the Company folder explains the format. In short:

  • A bullet is a rule for the AI. Add nested Bad: and Good: items so it can be tested. Paragraphs are context, not rules.
  • A table with the headers Avoid, Use, Severity, Why and Example becomes rules with exact fixes.
  • A table with the headers Rule, Setting and Reason disables rules or changes their level. House Style writes these rows for you when you use Disable Rule….

Change a Google rule

Select Disable Rule… in the issues pane, or use Rules. Choose the team or this project only, the new level, and why. For the team, House Style writes the change into the guide's Changes to the Google guide topic. A disabled rule is used by neither the linter nor the AI. See Browse and change style rules.

House Style ships with some Google rules disabled or changed for help topics, such as curly quotation marks and "this page". Each one is labeled Default in Rules, with its reason. You can enable any of them again.

Say where a rule applies

A rule applies to every topic unless you tag it with Flare condition tags:

  • Content tags, such as Steps, Code, Numbers or UI, limit a rule to sections with that content.
  • Product tags limit a rule to products. The guide's Product tag set lists the products it covers. Rules for other products never apply.

Check the guide

After you edit the guide, select House Style > Test Rules. It tests each rule table against its examples and finds rules that contradict or repeat each other. With AI, it also checks your team's written rules against their Bad and Good examples. To check Google's rules too, select Include Google's rules. That takes longer and costs more.

Build rules from evidence

Select House Style > Import Rules:

  • Mine this project finds where topics disagree, such as competing spellings or terms, with counts and example sentences. Pick the form to keep.
  • Add notes or an old guide… reads notes you paste or dictate, or a Word (.docx), web page (.htm), .txt or .md file. Select Extract rules.

Select a suggested rule to Edit rule… or Remove it. Then select Add checked rules to the guide.

Tune rules from review decisions

Select House Style > Rule Decisions. It collects the team's review decisions and lists rules that writers disagree on, rules they often ignore, edits several writers keep making, and requests. Each comes with its evidence. Draft a change with AI… rewrites a rule from that evidence as tracked changes in the guide.

Rule Decisions lists a rule only when enough writers made decisions on it, so one writer's preference doesn't change a shared rule.