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:
Mike Thomas 2024-08-14 07:27:27 +09:00 committed by GitHub
parent e9b2217ae8
commit 01014f53e6
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -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 cant 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 cant 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: