Titles and headings
Clear titles and headings help readers scan your content and give AI a quick, human-readable label for what an article or section covers. Good titles and headings make content easier to understand and navigate, for people and AI alike.
Titles
An article title should describe the topic clearly and specifically using the words your readers actually use.
- Be specific. "Reset a customer password" tells you what the article does. "Password information" does not.
- Use the reader's language. If customers typically ask "How do I cancel my subscription?", the title should include the words "cancel" and "subscription." A title like "terminate service" will be harder to find and understand.
- Focus on the outcome, not the feature or the internal system name.
Examples
Version numbers, status labels, and internal identifiers make a title harder to scan and add little value for readers.
| Before | After |
|---|---|
| Password Info | Reset a Customer Password |
| Billing | Update the Credit Card on Your Account |
| SSO Documentation | Set up Single Sign-On for your team |
| Article #4123 | Troubleshoot a failed order |
| MFA Configuration Guide V2 Final | Enable Multi-Factor Authentication |
Headings
Headings break an article into sections, and give people and AI models clean pieces of content to work with. When retrieval finds a relevant section, the heading is part of what tells the AI what that section is about.
Headings should be:
- Descriptive: Explain what is in that section without reading further.
- Consistent: If one heading is a question, do not make the next a noun phrase.
- Contextual: Relate to the section content, rather than serve as a generic placeholder.
Examples
Before
These headings give no context:
- Overview
- Details
- Additional Information
- Notes
After
Use headings that describe the actual content:
- When to use multi-factor authentication
- How to enable MFA for a single user
- How to enable MFA for your whole team
- Recovery options if a user loses their device
The "after" version reads like a useful table of contents, and each heading on its own is a signal about what that section contains.