Content can overwhelm readers if it’s not organized—especially when they’re trying to follow step-by-step instructions. Organizing content properly makes it easier for readers to access and use, which is the experience we strive to provide to anyone using our documentation.
There are several ways to organize content:
Write all documentation headings in sentence case and, in most cases, use an imperative verb, as the majority of our documentation instructs readers to do something. If the topic discusses other information, such as a primer on a module or other informational content, an imperative verb isn’t required since the reader isn’t being instructed to do something. A descriptive heading will suffice.
Exception: For other documents and writing, such as HR policies or marketing collateral, write titles in title case. Imperative verbs aren’t required but can be used depending on the subject matter and purpose of the document. These guidelines are mandatory for BriteCore help site documentation.
Exception: For advanced settings post titles, use only the name of the setting and remove the hyphens. Don’t begin advanced setting post titles with an imperative verb, and don’t include any other text. Use sentence case.
If a heading is immediately followed by lead-in/introductory text (not separated by other content), the lead-in text should provide additional information or otherwise vary from the text of the header. If it doesn’t, and solely restates the text of the heading, you don’t need it.
Example
Heading: Access the Contacts module
Lead-in text: To access the Contacts module…
In instances such as this, it’s acceptable to begin with step 1 after the heading. No lead-in text is necessary as it’s repetitive and serves no function.
Example
Heading: Access the Contacts module
Lead-in text: The Contacts module is BriteCore’s central repository for managing and editing contacts. Access the Contacts module by…
Lead-in text is appropriate in this context because it provide additional information beyond what the heading states.
Use your best judgment during your writing. Any issues or concerns will be addressed in editing.
Heading 2s
For documentation, which is all housed here in WordPress, the highest heading level is heading 2. Heading 1 formatting is automatically applied to all post and page titles. When a heading 2 precedes/introduces steps, use an imperative verb (a command verb that tells the reader to do something). If a heading 2 serves as an overview where its subordinate heading 3s precede/introduce instructions/steps, the heading 2 can be descriptive, and make the heading 3s imperative.
Exception: For other documents and writing, such as HR policies or marketing collateral, write titles in title case. Imperative verbs aren’t required but can be used depending on the subject matter and purpose of the document.
Examples
- Add a contact
- Submit a claim
- Create an email alert
- Contacts
- Claims
- Alerts
After the heading 2, you should generally include a brief introductory sentence or paragraph that provides the reader with context or other useful information. In general, for documentation, don’t follow a heading with another heading.
Heading 3s
When a heading 3 precedes/introduces steps, use an imperative verb. If a heading 3 serves as an overview where its subordinate heading 4s precede/introduce instructions/steps, the heading 3 can be descriptive, and make the heading 4s imperative.
Examples
- Add a contact
- Submit a claim
- Create an email alert
- Usage considerations
- Contacts permissions
Heading 2s in single- versus multi-topic documents
Don’t include a heading 2 in single-topic documents, as it will only repeat the text of the heading 1 (the page title). For documents with multiple subtopics, begin each with a heading 2 that uses an imperative verb.
Headings in multi-topic documents
For documents with multiple subtopics, begin each section with a heading 2 (and deeper heading levels, as applicable). Follow previous guidance regarding imperative/descriptive headings.
As previously mentioned, only include lead-ins after subheadings if they provide additional information, context, part of a step, or otherwise doesn’t simply restate the text in the heading.
Examples
- Single-topic document
- Multi-topic document without heading 3 lead-ins
- Multi-topic document with heading 3 lead-ins and heading 4s
Additional heading guidelines
Sometimes, a document will address additional considerations, usage considerations, etc. Use the title Additional considerations or Usage considerations, not Use considerations. Use considerations can be ambiguous in its meaning depending how the reader interprets the word use.
In addition:
- Don’t bold headings; this is applied via the WordPress template styling.
- Use sentence-style capitalization.
- Don’t apply code formatting in headings, as this will negate the heading formatting. Only use code formatting in body text.
- Try to avoid lengthy headings when possible.
- Don’t end headings with punctuation.
- Minimize use of en and em dashes.
- Don’t use ampersands (&) or plus signs (+).
- Break two-line headings thoughtfully.
- Be clear and concise.
- Focus on what matters to customers.
- Use parallel structure when applicable.
For more information, visit the Microsoft Style Guide Headings page.
Tables make complex information easier to understand by presenting it in a clear structure. In a table, data is arranged into two or more rows (plus a header row) and two or more columns. Don’t use a table just to present a list of items that are similar. Use a list instead.
| Tables are sometimes useful for | Example |
|---|---|
| Data or values | Text formats and their associated HTML codes |
| Simple instructions | User interface actions and their associated keyboard shortcuts |
| Categories of things with examples | BriteCore modules and the screens/functions they include |
| Collections of things with two or more attributes | Event dates with times and locations |
Content
Make sure the purpose of the table is clear. Include a brief introduction and a table title (before the table, not beneath it).
Bold the table reference and table title both before the table and wherever the Table # text appears elsewhere on the page. In the table title, also bold the colon. End table titles with a period. Also bold any named BriteCore UI elements.
Example:
Table 1 summarizes file functions and their descriptions.
Table 1: File function descriptions.
| Function | Description |
|---|---|
| AddUsersToEncryptedFile | Adds user keys to the specified encrypted file |
| Cancello | Cancels all pending input and output (I/O) operations that are issued by the calling thread for the specified file |
| CancelloEx | Marks any outstanding I/O operations for the specified file handle |
| GetTempFileName | Creates a name for a temporary file |
Make entries in a table parallel. For example, make all the items within a column a noun or a phrase that starts with a verb.
Place information that identifies the contents of a row in the leftmost column of the table. For example, in a table that describes commands, put the command names in the left column.
Don’t leave a cell blank or use an em dash to indicate there’s no entry for that cell. Instead, use Not applicable or None.
Balance row height by increasing the width of text-heavy columns and reducing the width of columns with minimal text.
Header rows
If the first row of your table contains column headings, you have a header row. Distinguish the text in the header row from the rest of the text in the table. For example, make it larger, bolder, or a different color.
Don’t organize a table so that the column heading forms a complete sentence when combined with the cell contents. This can make the table difficult to localize.
In long tables, make sure the header row is always visible. For example, on the web, use a fixed header row that stays in place during scrolling. Or, in a downloadable document, occasionally repeat the header row. Some authoring tools provide a way to do this automatically. In Microsoft Word, select the header row. On the Layout tab under Table Tools, select Repeat Header Rows.
Capitalization
Use sentence-style capitalization for the table title and each column heading. Use sentence-style capitalization for the text in cells unless there’s a reason not to (for example, keywords that must be lowercase).
Additional information about capitalization.
Punctuation
If there’s text that introduces the table, it should be a complete sentence and end with a period, not a colon.
Don’t use ellipses at the end of column headings.
For the text in cells, use periods or other end punctuation only if the cells contain complete sentences or a mixture of fragments and sentences.
Lists are a great way to present information so it stands out in a way that’s easy to scan.
Make items in a list parallel. For example, each item should be a noun or a phrase that starts with a verb. If items in a list are meant to complete a thought begun by a preceding introductory fragment, each item should also end with a period.
Bulleted lists
Use a bulleted list for things that have something in common but don’t need to appear in a particular order.
Example:
The database owner can:
- Create and delete a database.
- Add, delete, or modify a document.
- Add, delete, or modify any information in the database.
Note: In documentation, if a step in an ordered list of instructions includes a sublist of examples, options, etc., use bullets for those items, not numbering. Use numbering only to indicate sequence or progression. The inverse is also true; if an unordered list includes a sublist that is ordered, you can have a numbered sublist within a bulleted list.
Numbered lists
Use a numbered list for sequential items (like a procedure) or prioritized items (like a top 10 list).
Example:
To sign on to a database:
- On the File menu, select Open database.
- In Username, type your name.
- In Password, type your password, and then select OK.
Introductory text
Make sure the purpose of the list is clear. Introduce the list with a heading, a complete sentence, or a fragment that ends with a colon.
If you introduce a list with a heading, don’t use explanatory text after the heading unless such text is necessary and not redundant. Also, don’t use a colon or period after a heading.
Capitalization
Begin each item in a list with a capital letter unless there’s a reason not to (for example, it’s a proper noun, command line item, UI element, etc., that’s always lowercase).
Additional information about capitalization.
Punctuation
In bulleted and numbered lists, end each list item with a period if:
- Any item forms a complete sentence when combined with the list introduction that precedes the colon.
- Exception: Don’t use periods if all the items are UI labels, headings, subheadings, or strings.
- Any item by itself is a complete sentence.
- Don’t use semicolons, commas, or conjunctions (and, or, but) at the end of list items. List items will either end with a period or not.