|
| 1 | +# Editorial style guide rules |
| 2 | + |
| 3 | +When contributing to Markdown documentation, follow these style guidelines in order of precedence: |
| 4 | + |
| 5 | +1. **Chef-specific style** (this guide) |
| 6 | +2. **Google Developer Documentation Style Guide** principles |
| 7 | +3. **Third-party references** (Merriam-Webster, Chicago Manual of Style, Microsoft Writing Style Guide) |
| 8 | + |
| 9 | +## Markdown formatting |
| 10 | + |
| 11 | +### Voice and tone |
| 12 | + |
| 13 | +- Use active voice for all instructions - make clear who's performing the action |
| 14 | +- Use language like "You can" rather than "Users can" |
| 15 | +- Write clearly and conversationally |
| 16 | +- Be helpful and human |
| 17 | +- Passive voice is acceptable when you need to emphasize an object over an action, de-emphasize a subject, or when readers don't need to know who's responsible for the action |
| 18 | + |
| 19 | +### Language |
| 20 | + |
| 21 | +- Use clear, concise language and ensure there are no spelling or grammatical issues |
| 22 | +- Avoid jargon and use plain US English to ensure clarity for a global audience |
| 23 | +- Use the serial comma in lists |
| 24 | +- Use "select" instead of "click" or "click on" |
| 25 | +- Use "use" rather than "utilize" |
| 26 | +- Don't use Latin abbreviations, for example, instead of "e.g." use "for example", instead of "i.e." use "that is" |
| 27 | +- Don't replace "together with" with "alongside" |
| 28 | +- Use "go to" instead of "navigate to" |
| 29 | +- Instead of "via", use "through", "with", or "using" |
| 30 | +- Use contractions, for example, use "don't" rather than "do not" and "aren't" instead of "are not" |
| 31 | +- Don't use "please" |
| 32 | +- To introduce procedures, use an infinitive phrase with a comma and then the main clause. For example, "To save the document, follow these steps:" |
| 33 | +- Write for your audience - assume technical knowledge but explain complex concepts clearly |
| 34 | + |
| 35 | +### Verb tense |
| 36 | + |
| 37 | +- Use present tense for statements that describe general behavior not associated with a particular time |
| 38 | +- It's OK to use future tense (will) to distinguish an action that will occur in the future |
| 39 | +- Don't use future tense to describe how a product or feature will work after the next release or update |
| 40 | +- Avoid the hypothetical future "would" - use present tense instead |
| 41 | + |
| 42 | +### Product names |
| 43 | + |
| 44 | +- Use "Chef 360 Platform" instead of "Chef 360" or "Chef 360 platform" |
| 45 | + |
| 46 | +### Procedures |
| 47 | + |
| 48 | +When writing step-by-step instructions, follow these guidelines: |
| 49 | + |
| 50 | +#### Introductory sentences |
| 51 | + |
| 52 | +- Introduce procedures with context that isn't part of the section heading |
| 53 | +- Don't simply repeat the heading |
| 54 | +- End with a colon if it immediately precedes the procedure, or a period if there's material between the introduction and procedure |
| 55 | +- Use imperative statements: "To customize the buttons, follow these steps:" or "Customize the buttons:" |
| 56 | + |
| 57 | +#### Single-step procedures |
| 58 | + |
| 59 | +- Format single steps as bulleted lists, not numbered lists |
| 60 | +- Write the step in one sentence |
| 61 | + |
| 62 | +#### Multi-step procedures |
| 63 | + |
| 64 | +- Use numbered lists for sequential steps |
| 65 | +- Use one step for each action |
| 66 | +- Combine small sequential actions using angle brackets (>) for menu selections |
| 67 | + |
| 68 | +#### Step structure |
| 69 | + |
| 70 | +- Start each step with an imperative verb |
| 71 | +- Use complete sentences |
| 72 | +- Use parallel structure and consistent verb forms |
| 73 | +- State the location before the action: "In the Google Cloud console, go to the Monitoring page" |
| 74 | +- State the goal before the action: "To start a new document, select **File** > **New** > **Document**" |
| 75 | +- Keep results in the same paragraph as the action |
| 76 | + |
| 77 | +#### Optional steps |
| 78 | + |
| 79 | +- Start optional steps with "Optional:" followed by a colon |
| 80 | + |
| 81 | +#### Step organization |
| 82 | + |
| 83 | +- Describe the action first |
| 84 | +- List commands if necessary |
| 85 | +- Explain placeholders used in commands |
| 86 | +- Explain commands in detail if necessary |
| 87 | +- List command output if necessary |
| 88 | +- Explain results in a separate paragraph if necessary |
| 89 | + |
| 90 | +### Headings and titles |
| 91 | + |
| 92 | +When writing headings and titles, follow these guidelines: |
| 93 | + |
| 94 | +#### Heading text and structure |
| 95 | + |
| 96 | +- Write document titles based on the primary purpose of the document |
| 97 | +- For task-based headings, start with a bare infinitive (base form verb): "Create an instance" not "Creating an instance" |
| 98 | +- For conceptual headings, use a noun phrase that doesn't start with an -ing verb: "Migration to Google Cloud" not "Migrating to Google Cloud" |
| 99 | +- It's OK to use both task-based and conceptual heading styles in the same document |
| 100 | +- When possible, avoid using -ing verb forms as the first word in headings or titles |
| 101 | +- Avoid repeating the exact page title in a heading on the page |
| 102 | + |
| 103 | +#### Heading format |
| 104 | + |
| 105 | +- Use sentence case for headings and titles (don't use uppercase) |
| 106 | +- Don't include numbers in headings to indicate a sequence of sections |
| 107 | +- Use punctuation in headings sparingly - punctuation can be a sign that your heading is too complicated |
| 108 | +- Only use abbreviations in headings if they're more commonly known than the full term |
| 109 | +- Use heading tags to structure content hierarchically (h1, h2, h3, etc. or #, ##, ### in Markdown) |
| 110 | +- Don't skip levels of the heading hierarchy - put h3 only under h2, etc. |
| 111 | +- Don't use empty headings or headings with no associated content |
| 112 | +- Don't put links in headings as they can be confused with heading styles |
| 113 | +- Avoid using code items in headings when possible |
| 114 | + |
| 115 | +#### Referring to sections |
| 116 | + |
| 117 | +- When introducing a group of related H3 or lower sections within a larger H2 section, use "the following sections" |
| 118 | +- Don't refer to groups of sections as "this section" or "these sections" as these phrases are ambiguous |
| 119 | + |
| 120 | +### User interface elements |
| 121 | + |
| 122 | +When documenting UI elements, follow these guidelines: |
| 123 | + |
| 124 | +#### Focus on the task |
| 125 | + |
| 126 | +- State instructions in terms of what the reader should accomplish, rather than focusing on widgets and gestures |
| 127 | +- When practical, avoid reference to UI elements to help readers understand the purpose |
| 128 | +- Provide the level of detail that seems useful for the intended audience |
| 129 | + |
| 130 | +#### Format UI element names |
| 131 | + |
| 132 | +- Put UI element names in bold using `**` in Markdown |
| 133 | +- This includes buttons, menus, dialogs, windows, list items, or any other feature with a visible name |
| 134 | +- Don't use code font for UI elements unless they meet requirements for code font |
| 135 | +- Follow the capitalization as it appears on the page, but use sentence case if labels are inconsistent or all uppercase |
| 136 | + |
| 137 | +#### UI element terminology |
| 138 | + |
| 139 | +- **Button**: Use the button's label - "Select **OK**" not "Select the OK button" |
| 140 | +- **Checkbox**: Use "the LABEL_NAME checkbox" - "Select the **Automatically check for updates** checkbox" |
| 141 | +- **Menu**: Use "In the MENU_NAME menu" or use angle brackets (>) for menu paths |
| 142 | +- **Text field**: Use "field" instead of "box" - "In the **Name** field, enter your username" |
| 143 | +- **Dialog**: Use "dialog" not "pop-up window" |
| 144 | +- **Tab**: Use "the LABEL_NAME tab" |
| 145 | +- **Toggle**: Don't use "toggle" as a verb - "To turn on the setting, click the **Wi-Fi** toggle" |
| 146 | + |
| 147 | +#### Verbs for UI interactions |
| 148 | + |
| 149 | +- Use "select" instead of "click" or "click on" |
| 150 | +- Use "enter" or "type" for text input |
| 151 | +- Use "choose" for selecting from options |
| 152 | +- Use "turn on" or "turn off" for toggles and switches |
| 153 | +- Use "clear" instead of "uncheck" for checkboxes |
| 154 | + |
| 155 | +#### Prepositions |
| 156 | + |
| 157 | +- Use "in" for: dialogs, fields, lists, menus, panes, windows |
| 158 | +- Use "on" for: pages, tabs, toolbars |
| 159 | + |
| 160 | +### Formatting |
| 161 | + |
| 162 | +- Use sentence case for headings (don't use uppercase) |
| 163 | +- Use "1." for each item in an ordered list |
| 164 | +- If there's one step in a procedure, use one bulleted list item (-) before the step instead of "1." |
| 165 | +- Use bulleted lists (rather than numbered lists) when it's just a list of points and not a sequential list of instructions |
| 166 | +- Use semantic line breaks where each sentence is on a separate line |
| 167 | +- Format code and UI elements consistently |
| 168 | +- Use three hyphens (---) instead of em dashes (—) |
| 169 | +- Use two hyphens (--) instead of en dashes (–) |
| 170 | + |
| 171 | +### Links |
| 172 | + |
| 173 | +- Ensure that all hyperlinks are descriptive and provide context for the destination content |
| 174 | +- Add mailto link tags for email addresses |
| 175 | +- Use meaningful link text that describes the destination |
| 176 | + |
| 177 | +### Quality principles |
| 178 | + |
| 179 | +- Be consistent throughout your documentation |
| 180 | +- Prioritize clarity over brevity when necessary |
| 181 | +- Break style rules when doing so improves content quality |
| 182 | +- Test your instructions to ensure they work as written |
| 183 | +- Update documentation when products or processes change |
| 184 | + |
| 185 | +### Accessibility |
| 186 | + |
| 187 | +- Write clear headings that describe the content that follows |
| 188 | +- Use alt text for images that describes their content and purpose |
| 189 | +- Ensure proper contrast and readability |
| 190 | +- Structure content logically with appropriate heading levels |
0 commit comments