mirror of
https://github.com/fleetdm/fleet
synced 2026-05-23 08:58:41 +00:00
Handbook: guidelines for consistent headings and titles (#21172)
To help the team write better, more consistent docs and guides: - I added guidelines for writing headings and titles. In particular for reference vs. guides. - I cleaned up that handbook section while I was there. # Checklist for submitter - [x] Manual QA for all new/changed functionality
This commit is contained in:
parent
e9b2217ae8
commit
01014f53e6
1 changed files with 36 additions and 7 deletions
|
|
@ -1118,21 +1118,50 @@ As we use sentence case, only the first word is capitalized. But, if a word woul
|
|||
- When talking about a users' computer, we prefer to use "device" over _endpoint._ Devices in this context can be a physical device or virtual instance that connect to and exchange information with a computer network. Examples of devices include mobile devices, desktop computers, laptop computers, virtual machines, and servers.
|
||||
|
||||
|
||||
### Headings
|
||||
### Headings and titles
|
||||
|
||||
Headings help readers quickly scan content to find what they need and guide readers through your writing. Organize page content using clear headings specific to the topic they describe.
|
||||
Headings and titles should give an accurate idea of a topic's content and help guide readers through your writing so they can quickly find what they need.
|
||||
|
||||
While our readers are more tech-savvy than most, we can’t expect them to recognize queries by SQL alone. Avoid using code for headings. Instead, say what the code does and include code examples in the body of your document.
|
||||
#### Static headings
|
||||
|
||||
Use static headings (a `noun` or `noun phrase`) e.g., “Log destinations,” for concept or reference topics. Be as short and specific as possible.
|
||||
|
||||
#### Task-based headings
|
||||
|
||||
Use task-based headings (`verb` + `topic`) e.g., _“Configure a log destination”_ for guides and tutorials where the heading should reveal the task that the reader is trying to achieve.
|
||||
|
||||
#### Avoid _-ing_ verb forms in headings
|
||||
|
||||
Avoid starting a heading with _-ing_ verb form, if possible.
|
||||
|
||||
_-ing_ verb forms are more difficult for non-native English readers to understand, translate inconsistently, and increase character counts in limit spaces, such as in docs navigation.
|
||||
|
||||
| ✅ Recommended | ❌ Not recommended |
|
||||
| ---------------- | -------------------- |
|
||||
| “Configure a log destination” | “Configuring a log destination” |
|
||||
|
||||
#### Avoid vague verbs in headings
|
||||
|
||||
Were possible, avoid starting a heading with a vague verb, like “understand,” “learn,” or “Use.” Headings that start with a vague verb can mislead readers by making a topic appear to be task-oriented (a guide) when it is actually reference or conceptual information.
|
||||
|
||||
| ✅ Recommended | ❌ Not recommended |
|
||||
| ---------------- | -------------------- |
|
||||
| “Log destinations” | “Understand log destinations.” |
|
||||
|
||||
|
||||
#### Avoid code in headings
|
||||
|
||||
While our readers are more tech-savvy than most, we can’t expect them to recognize queries by SQL alone. Avoid using code for headings. Instead, say what the code does and include code examples in the body of your document. That aside, it doesn't render well on the website.
|
||||
|
||||
#### Heading hierarchy
|
||||
|
||||
Use heading tags to structure your content hierarchically. Try to stay within three or four heading levels. Detailed documents may use more, but pages with a simpler structure are easier to read.
|
||||
|
||||
Keep headings brief, organized, and in a logical order:
|
||||
- H1: Page title
|
||||
- H2: Main headings
|
||||
- H3: Subheadings
|
||||
- H4: Sub-subheadings
|
||||
|
||||
Try to stay within three or four heading levels. Detailed documents may use more, but pages with a simpler structure are easier to read.
|
||||
|
||||
|
||||
#### Punctuation in headings
|
||||
|
||||
Fleet headings do not use end punctuation unless the heading is a question:
|
||||
|
|
|
|||
Loading…
Reference in a new issue