Taking some time to consider your headings and document titles is time well spent. Titles and headings are not only important for search results, but they can make your docs easier to skim.
For all headings, subheadings, and titles use sentence case. This means you should capitalize the first word of the title and proper nouns only. You should also capitalize the first word after a colon. Avoid dashes and ellipses in headlines and titles. Avoid using punctuation, with the exception of question marks.
Use parallel construction
Use parallel construction when naming headers. For example, use all nouns ("Organization," "Tone"), all verbs ("Create," "Delete"), etc.
Keep it short, avoid -ing words
For all headers, keep the title as short as possible. In particular, avoid headers that are more than a line long. As with all our writing, you should feel free to address the reader directly: Install the agent, for example, rather than Agent installation. You should also avoid -ing words, which add to character count without contributing clarity.
Do not use h1 headings
After you publish your doc, the docs site will automatically use what you added to the Title field as the doc's level one heading (h1). To ensure that your doc is properly indexed for search, do not manually create additional h1 headings.
If your doc's title is long and you would like a shorter title to appear in the sidebar menu, create a GitHub issue and we'll help you with that change.
Use level two headings to identify chunks of information
Organize chunks of information into sections with level two headings (##). For example:
## Create a new user [#create-new-user]중요
If you don't specify an ID manually, the site will use your header text as that header's ID (also known as anchor link). Create a manual ID to preserve links to that header if you change the header text.
If you have too many level sections, consider splitting the document into multiple pages.
Avoid using level three headings
Avoid using ### headings unless it makes sense for the content or if the content is lengthy. Collapsers, tables, and other structural elements are often a better choice. Be particularly careful about level three headings that make a level two section longer than a single screen height.
Here are two examples of good scenarios for using level three headings:
- Example #1: Events-to-metrics API doc
- Example #2: Infrastructure integration doc