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.
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!