Headings and Titles
Both provide structure and visual reference points to help readers scan content. Structuring headings in a hierarchy can make a larger topic easily scannable while helping search engines understand the context of your content.
By following these practices, you can effectively structure your writing and improve the overall presentation of your content.
Capitalization in titles
Titles are typically written in title case, where the first letter of each major word is capitalized. Headings, however, are often written in sentence case, where only the first letter of the first word is capitalized (unless there are proper nouns or acronyms). This helps to differentiate between the two and maintain consistency in formatting throughout a document or piece of writing.
Use title case in titles to distinguish the main topic from subsections or parts within the topic.
Title case for titles:
- Emphasis: Title case helps emphasize the title's importance and make it stand out.
- Clarity: Capitalizing the first letter of each major word in a title improves readability and comprehension.
- Consistency: Using title case for titles maintains consistency in formatting across different titles.
Capitalization in headings
Use sentence case in headings to improve readability. Capitalize only the first word in the title, the first word in a subheading after a colon, and any proper nouns, product and feature names.
Sentence case for headings:
- Readability: Sentence case is easier to read, especially for longer headings or subheadings.
- Natural flow: Sentence case mimics the natural flow of a sentence, making headings more approachable.
- Less formality: Sentence case is less formal than title case, making it suitable for organizing content within a document.
Using sentence case represents the difference between proper nouns and other words. Plus, it feels more approachable. It's also easier to read and scan.
Correct
Change process for Patterns
Installing the dependencies
Installing the software
Incorrect
Change Process for Patterns
Install the Dependencies
INSTALL THE SOFTWARE
Effective headings
Makes it clear which sections of a document are most relevant to their current tasks.
Keep headers short and place the most important idea at the beginning. If there is a lot to say, use lower-level headings to break up the section into smaller, more scannable chunks.
Use descriptive headings and subheadings to guide the user through the document. It also gives readers a good sense of progress while moving from one task to the next.
Correct
Getting access to Ansible Tower
HINT! The verb implies that it's a "how-to" topic.
Incorrect
Ansible Tower - How to get Access
Gerunds in headings and titles
It makes headings and titles more concise and easier to understand. It also helps maintain an active voice for clarity and directness.
Correct
Migrating to AWS
Transferring data sets
Incorrect
Migrate to AWS
Transfer data sets
Use 'and' in headings
In headings, use 'and' instead of '&' or '+' unless the reference is to the UI or space is limited.
Correct
Installation and setup guide
Features and benefits
Incorrect
Installation & Setup Guide
Features + benefits
Keep headings short
If there is a lot to say, use lower-level headings to break up the content into smaller chunks (sections) and easier to scan.
Correct
Network configuration settings
Incorrect
Comprehensive guide to configuring network settings for different devices and environments
Use 'vs.' in headings
Instead of using 'v.' or 'versus' in headings, use the 'vs.' abbreviation. It's a compromise as it is shorter than 'versus' but maintains clarity.
Correct
HTTP vs. HTTPS: Understanding the differences
Best practices for Git Merge vs. Rebase
Incorrect
HTTP versus HTTPS - What's Different?
Merging v Rebasing in Git - A Comparison
Organization of headings
When headings and subheadings visually stand out on the page and are descriptive, users engage in a Layer Cake scanning pattern that allows them to find the information that they need quickly.
- Maintain the heading hierarchy throughout the doc. Don't skip heading levels.
- Avoid having two headings in a row without text in between (empty headings), as they may indicate a problem with organization or redundancy.
- Avoid using filler text to separate headings. Instead, provide an intro paragraph following the guidelines below.
Correct
H1: Setting up your environment
H2: Installation
H3: Downloading the software
H3: Running the installer
H2: Configuration
H3: Basic configuration
H3: Advanced configuration
This structure organizes content from general to specific, making it easy for readers to navigate the document. Each heading level logically follows the previous, guiding the reader down a structured information path.
Incorrect
H1: Getting started
H2: Downloading the software
H2: Running the installer
H2: Basic configuration
H2: Advanced configuration
This structure lacks differentiation between main topics and subtopics, creating a flat hierarchy. It treats all aspects of the setup process with equal weight, making it harder for users to distinguish between stages of the process.
Step numbers in headings
When writing scenario—or goal-based content (task-based), you will likely need to break down a long procedure into smaller sections. Using steps in headings can help organize procedural content, making it easier for readers to follow a sequence of actions.
Correct
Step 1: Install the software
Step 2: Configure your settings
Incorrect
Installation
Configuration
Punctuation in headings
When writing scenario—or goal-based content (task-based), you will likely need to break down a long procedure into smaller sections. Using steps in headings can help organize procedural content, making it easier for readers to follow a sequence of actions.
Correct
Setting up your account
Found a bug? Contact support!
Installation and setup guide
Incorrect
Setting up your account.
Bug reporting
Installation, setup, and configuration guide
Acronyms in headings
Using acronyms and abbreviations in headings can be tricky because while they save space, they might not be immediately apparent to all readers. It's essential to balance brevity with clarity.
Using the acronym or abbreviation in headings is acceptable if it is widely recognized.
Correct
Understand CPU performance metrics
Incorrect
Understanding Central Processing Unit (CPU) performance metrics
Task and procedure headings
Always start with a verb and use sentence case. The verb implies that it's an action of a how-to content type.
Correct
Building an API response
Setting the active build configuration
Resetting your password
HINT! The verb implies that it's a "how-to" topic.
Incorrect
How to build an API response
Active build configuration
How to handle password resets
Non-task headings
Use noun phrases and sentence cases for conceptual, overview, architecture, and reference information.
Correct
Principles of secure coding
Overview of Cloud Computing
Version control basics
Incorrect
Secure coding: What's the big deal?
What you need to know about Clouds
How to save your work