Blog

“Troubleshooting” tells readers almost nothing about what comes next. “Check Why Java Is Not Found in Your Terminal” names the problem, so someone scanning the page knows where to stop. A good heading describes the section beneath it closely enough that readers can decide whether to read it now, skip it, or come back later.

That matters in technical guides, where readers often need one answer rather than the whole page. Someone fixing a Linux permission error may need a single command explained. Someone learning C++ may be looking for the difference between a compiler error and a runtime error. Clear headings help both find the right passage without guessing what “Getting Started” or “Other Considerations” might contain.

Give each heading a specific job

Before writing a heading, ask what the section does. Does it explain a concept, walk through a task, compare options, or diagnose a failure? Make that purpose visible. “Set Up a Java Development Kit” promises instructions; “What the JDK Includes” promises an explanation. Swap one for the other and readers arrive with the wrong expectation.

A useful heading usually names the subject and, where needed, a distinction. “Install Git” may be enough in a guide devoted to that installation. On a page covering several operating systems, “Install Git on Ubuntu” removes a real ambiguity. Add detail because it helps readers choose a section, not just to make the heading longer.

Write plain-language headings first. If a section is hard to name, it may be doing too much. Installation steps, configuration choices, and error fixes often deserve separate sections, each with a heading that matches its contents. That also makes the page easier to update later.

Build a hierarchy that matches the content

The page title identifies the main topic. Put major sections under h2 headings and narrower parts under h3 headings. Treat those levels as an outline, not a way to choose font sizes. Making text larger does not make it a new topic, and wanting smaller text is no reason to skip a heading level.

Keep parent and child headings connected

An h2 called “Diagnose a Failed SSH Connection” might contain h3 sections called “Confirm the Host Address,” “Check Whether the Service Is Running,” and “Read the Client Error Message.” Each covers part of the diagnostic task. “Choosing a Text Editor” belongs elsewhere, regardless of how large the author wants it to look.

One major section may have several subsections while its neighbors have none. That is not necessarily a problem; some tasks need more detail. Check whether each subsection belongs under its parent and whether that relationship is clear from the headings alone.

Do not use headings as decoration

Headings introduce sections. They are not a substitute for a bold warning, an emphasized sentence, or extra space on the page. A brief caution can be a paragraph with a bold lead-in. Several one-sentence sections might work better as a list under one heading. Let the hierarchy describe the information, not the editor’s formatting.

Write for someone scanning without context

Readers may see the headings before the introduction, in a contents menu, or in a screen-reader heading list. “Step Two” and “The Next Issue” reveal little on their own. “Add the Compiler to Your PATH” and “Check the File’s Ownership” tell readers what they will find.

There is no ideal heading length. Keep it easy to scan, but specific enough to distinguish it from nearby sections:

• Too broad: “Security”
• More useful: “Limit Who Can Read the Configuration File”
• Needlessly long: “Important Security Considerations to Think About Before You Change the Configuration File Permissions”

Use concrete verbs for tasks: “Create a Test Directory,” “Verify the Backup,” or “Compare the Error Messages.” Explanations may be clearer as a noun phrase or question, such as “How File Permissions Affect a Service” or “What Does This Warning Mean?” The wording should suit the section; every heading need not be a command.

Think about when beginners will recognize a term. “Configure UFW Defaults” works if the guide has already introduced UFW. Earlier on, “Set Default Firewall Rules” gives readers more context. Technical terms help when they identify the subject precisely, but unexplained jargon can make a heading harder to use.

Make headings accurate, not merely attractive

A heading makes a promise. “Fix Every Linux Permission Error” is misleading if the section covers only one cause. “Check Permissions on the Log Directory” is narrower and easier to verify. Questions need to deliver, too: “Why Is My Program Slow?” should lead to an explanation or a diagnostic path, not just a definition of performance.

Read the first and last paragraphs beneath each heading. If the section shifts to another task halfway through, change the heading or move the material. Put important limits where readers can see them. When instructions apply only to a local practice environment, “Inspect Open Ports in Your Own Lab” makes the scope clearer than “Inspect Open Ports.”

Keep headings distinct across the page. Three sections called “Testing” make readers open each one to learn what is being tested. “Test the Installation,” “Test the Configuration,” and “Test the Recovery Procedure” show the differences at a glance. Repeated wording can establish a useful pattern; identical labels for different subjects cannot.

Edit the outline before editing every sentence

Once the draft exists, copy its headings into a separate outline or open the editor’s document outline. Read the headings without the body text. Do they follow a sensible order? Can you tell what each section covers?

1. Replace vague labels. Swap “Overview,” “Tips,” or “Advanced” for a more precise description when one is available.
2. Check the order. Put prerequisites before the steps that need them, and verification after the action being checked.
3. Check the levels. Keep subsections under the section they explain. Do not jump from an h2 to an h4 for visual effect.
4. Match promise to content. Change any heading that suggests something the section does not deliver.
5. Scan on a narrow screen. If a heading wraps awkwardly on a phone, cut filler without losing the words that make it specific.

Then inspect the rendered page. Headings should look different from body text, but appearance is only part of the check. Confirm that their underlying levels match the outline. An editor’s heading-navigation view can help catch text styled to look like a heading or assigned the wrong level.

Handle steps, code, and safety notes carefully

A heading should describe the task around a code example, rather than repeat the command as its only label. “Check the Installed Java Version” is easier to scan than a heading that says only java -version. Place the command in the section, where you can explain what it does and what output to expect.

Keep step headings parallel when they form a sequence. “Create a Project Directory,” “Add the Source File,” and “Compile the Program” make the workflow easy to follow. Switching to “Directory Creation,” “You Should Add the Source File,” and “Compilation Time” makes the sequence harder to scan. Parallel wording helps within a set of steps; it does not need to govern every heading on the page.

Security-related headings need particular care. “Disable the Firewall to Test Connectivity” can make an unnecessary change sound routine. If the procedure is actually to inspect a controlled lab setup, call it “Check Firewall Rules in Your Test Environment.” The section can then state the authorized scope and explain how to restore any temporary change.

Before publishing, pick a heading and read only its section. If it explains how to confirm that a backup completed, “Verify the Backup Files” tells a scanning reader more than “Backup Complete.” Make that same check wherever a heading might imply a result the reader still needs to verify.