Use of `#` header levels

I'd like to ask about best practices for use of header levels (#, ##, ###, etc).

DocC seems to use 2nd-level headers (##) for marking major sections in the document. These appear in the TOC, and a selection of names are reserved: ## Overview, ## Topics, and ## See Also, which are formatted in a special way.

First question: When is it okay to use our own 2nd-level headers, and how do we know DocC won't reserve these in the future? I'm thinking of using some headers like ## Formats and ## Languages, but I worry DocC might take those one day.

Second question: Can we customise the level of the TOC? For some pages, the current h2 limit is really bad. For example, in the DocC article "Formatting Your Documentation Content", the TOC is basically useless. Trying to find important sections, such as how to add images, lists, or tables, requires scrolling through the entire article.

Or - Is the advice that this article should be making use of 2nd-level headers instead? To explicitly add items to the TOC and group things in a logical order?

1 Like

Hi Karl,

See my comments inline to your questions:

DocC seems to use 2nd-level headers ( ## ) for marking major sections in the document. These appear in the TOC, and a selection of names are reserved: ## Overview , ## Topics , and ## See Also , which are formatted in a special way.

First question: When is it okay to use our own 2nd-level headers, and how do we know DocC won't reserve these in the future? I'm thinking of using some headers like ## Formats and ## Languages , but I worry DocC might take those one day.

Great question. There are very few instances in documentation where you may encounter common or standard names for section headers. One I can think of off-hand is the first section header in a technology page: ## Essentials.

This section header title introduces the absolute essential elements of a technology for readers to investigate first.

There's also ## See Also as you noted. Outside of these two examples, you should feel confident to choose your own section header titles. And of course, if you use section titles with two or more words, the chances of a collision with any future common title diminishes considerably. :slight_smile:

You do bring up an important point. I'll discuss your concern and see if we can provide some guidance on this.

Second question: Can we customise the level of the TOC? For some pages, the current h2 limit is really bad. For example, in the DocC article "Formatting Your Documentation Content" , the TOC is basically useless. Trying to find important sections, such as how to add images, lists, or tables, requires scrolling through the entire article.

Or - Is the advice that this article should be making use of 2nd-level headers instead? To explicitly add items to the TOC and group things in a logical order?

Second-level section headers are for the overview, which always comes at the top of the article. Third-level section headers always follow. I don't recall an instance where second-level section headers are used further down in an article. So unless someone can provide a counter-example, an article is always organized with a first-level section header, followed by a second-level-section header, then any number of third-level section headers.

I looked at the article you referred to, and I count nine three-level (###) section headers. There is a lot of information to convey there. This comes down to the Solomonic choice that we as writers are often faced with: what is "too long" and where, if anywhere, to split an article into separate articles.

As you indicate, you're faced with scrolling through a long article get to the parts you may be interested in. In general I aim to make my articles a bit shorter if possible. There may be ways to take this article, for example, and turn it into two articles by splitting the three-level section headers into two groups: one group focusing on page titles, section headers, text formatting, code listings, special characters, and symbol linking. The other group would focus on images, bulleted/numbered lists, tables, and notes/asides. Then you could turn each "group" into a separate article, with the goal of keeping both articles at roughly the same length.

This is where the "art" and "science" of writing come together in what I call "the writer's nebula." It's sometimes hard to know where one ends and the other begins. You may feel that there is no one "right" way to organize lots of content. That's when experimentation comes into play, and after some number of iterations, you discover an organizational solution that looks and feels right. :)

I hope this helps!

5 Likes

So this is what I'm unsure about - is the use of a second-level headers solely up to editorial choice, or is there a non-stylistic reason that, as far as I can find, none of the DocC documentation or articles seem to use second-level headers?

The specific article I mentioned could be split in to several articles - but there is also value in having it be a single article, because it allows users to more easily browse. Perhaps it just needs to make greater use of the organisational features available; does it really make sense for the entire body of an article to live in its "Overview" section?

But it's not just that one article; it's a clear pattern across the DocC documentation (as you say, it's hard to recall seeing a simple example of other second-level headers). It makes it seem like this organisational feature is not available or is discouraged for some reason.

I think there's a lack of documentation (ironic) in what is supported by DocC vs. what is just recommended / those responsible for DocC have established as their writing patterns.

DocC will support any 2nd level headers, and render them in the ToC, it's just some are blessed and have their own behaviors (notably "See Also").


By default, if no 2nd level header is provided after the 2nd line of the file (the 1 line summary) portion, then DocC automatically adds "## Overview".

# ``TimePeriod``
An overview guide on using one of the most widely used type in **Time**.

``TimePeriod`` is perhaps the complicated part of the **Time** package. It represents "a value that can be understood as being calendrically significant".

A more colloquial definition might be: "If you can point to it on a calendar or clock, it's a `TimePeriod`".

However, you can provide your own 2nd level that is completely custom, and DocC will render it instead of "Overview".

# ``TimePeriod``
<summary>

## Something Else
``TimePeriod`` is perhaps the ...

You could even have your own defined "Overview" later in the document and it'll render it just fine, even duplicating if necessary

# ``TimePeriod``
<summary>

<first overview>

## Overview
<second overview>

1 Like

DocC's only limitation for TOC control/support is anything 3rd header or lower.

I would like to see support for 3rd level, but agree that 4th or lower shouldn’t be.

I’d think at that point if you’re wanting/needing the headers in the TOC then you should review your article’s structure

1 Like

i didn’t mark it down when it happened, but i’ve also had some H2 style heading (##) just ignored and not displayed.