Clarify use of sub-headings in concepts and references

[sterobin]

Subheadings in con and ref modules comes up a lot in team discussions and in my mod doc repos course. So we should add a brief paragraph to each module type in the ref guide noting that concepts and references can have sub-headings if needed for organizing the content better and if the sub-headings are truly helpers and cannot/should not be separate modules. This is not true for procedures, which should always contain the one heading plus labels.

Also clarify that when sub-headings are used, the understood default to date is to [discrete] the heading, if you have a need to display the sub-headings in the TOC, permitted to not use [discrete]. But the use case must be deliberate, such as API endpoints that can be extensive. You don't always want them as individual ref modules, but also want them displayed in TOC for easier nav. So okay to have a parent ref module that contains all endpoints as subsections without [float].

[sterobin]

Submitted PR #140

[sterobin]

Resolved in above-mentioned PR.

[rkratky]

@sterobin, apologies for being so late to the party.

I believe we should resolve this issue by providing solid info on what constitutes a module. I think we already have that in the mod docs glossary:

Module

An independent, self-contained chunk of information with a well-organized structure. Each module is information that a reader can understand and use by itself. A writer can use a module as a standalone article or as part of a larger body of work (an "Assembly"). A module does not depend on other documents, but it can refer the reader to other documents as additional resources. Because a module is self-contained, it must have a clear title that briefly and clearly summarizes the subject of the module. Moreover, because modules are written as context-free elements independent of other modules, they are re-usable. One module can be part of multiple assemblies. [...]

This is very clear. Perhaps we need to highlight this in another part of the guide, or include it more prominently in training sessions. We should not try to invent rules or overly restrict the way writers use their judgement. As long as writers follow the cited guideline, their modules will conform to mod docs requirements -- they will be reusable and self-contained. Whether the writer chooses to use subtitles or not is up to them and their particular content situation.

[sterobin]

@rkratky , exactly. The sole purpose of this issue and PR was not to restrict but in fact to liberate writers to the option of dividing up con and ref modules into sub-headings as needed within the same module, if needed. The reason for this PR is that there is a false notion out there that sub-headings aren't permitted in any module ever, and if you need to subdivide, use separate standalone modules instead. As a result, writers are creating overly minute, artificial modules that really aren't standalone simply because they need to divide up the info a bit and think they can't use subheadings. So again, this PR simply clarifies that subheadings are perfectly fine in cons and refs, with the caveat that they need to be sure to meanwhile follow the guidance you've referenced on ensuring that subdivided content is truly not standalone. If it is, then separate module.

Again, I'm not introducing anything new with this, just clearing up a misnomer out there that subheadings are prohibited, which isn't true. Just about using them judiciously.

Regarding the direction to not using subheads in procs, however, that's a separate issue and has been the suggestion from the beginning, back with Christy and Sheldon. That would be a topic for a team discussion and revision if needed.