How To Write A Docs Page

Why help pages are different

Nobody reads a help page for fun. They show up with one question, scan for the answer, and leave. A good docs page is built for scanning: short sections, clear headings, and the answer right under the heading that promises it.

How this layout works

Every page in this Help Center uses one WordPress page template. I write the page in the regular editor, and the template does the rest:

• Every H2 heading becomes a numbered link in the sidebar automatically.
• The sidebar highlights the section you’re reading as you scroll.
• The page’s Excerpt becomes the intro line under the title.
• A parent page turns into a breadcrumb at the top.
• The “Last updated” date comes from the page’s last edit.

There’s nothing to set up per page. Write good headings, and the navigation builds itself.

Write headings as answers

Your H2s are your table of contents, so make each one tell the reader what’s underneath it.

Vague	Clear
Settings	Change your time zone
Info	What happens when the timer ends
Problems	The time is off by a few hours

A reader should be able to find their answer by reading the sidebar alone.

Keep each section short

• One idea per section. If a section needs its own sub-sections, it probably wants to be two H2s.
• Lead with the answer, then explain. Don’t make people read the background to find the step.
• Use numbered lists for steps people do in order, and bullets for everything else.
• Put anything people will copy in a code block, so it’s easy to select.

Show real examples

An example people can copy beats a paragraph describing what to type. If an option has a default value, say what it is. If something can go wrong, show what it looks like and how to fix it.

One WordPress gotcha: if you show a shortcode as an example, WordPress will run it, even inside a code block. To show it without running it, wrap it in double brackets. [[my_shortcode]] displays on the page as [my_shortcode].

Keep it current

An outdated help page is worse than none, because people trust it. When something changes, update the page the same day. The “Last updated” line at the bottom tells readers how fresh it is, and tells you when it’s due for a look.