Revert H2 section headings to block headings for procedures, prereqs, and additional resources.

[sterobin]

As discussed in ccs-mod-docs distro list with email subject "Clarification on block heading vs. sub-heading for prereqs, procedures, etc.", I've reverted Procedure, Preq, and Additional headings to previous block format in templates and Ref Guide (.Procedure, .Prerequisites, etc.) everywhere except for Additional resources in assemblies specifically, which should remain an un-discrete "== Additional resources" for now. That too can be reverted to block format once the tooling team finishes the fixes on modules and moves on to assemblies. See the considerations below. I also adjusted some structural inconsistencies in the Ref Guide while I was at it.

Summary of considerations:

• Tooling/stylesheet solutions to the minor output glitch: It's true that there is a minor glitch in the output when we use .Procedure etc. (it might vary in size slightly sometimes), and that .Procedure looks virtually the same as .Table or .Figure in some cases (I'd argue that they are similar types of content anyway and thus suitable as similar labels and not headings). But this is a tooling/stylesheet issue now being handled (as it should be) by the tooling team in FCC Phase 1, for modules at least. The same issue will be addressed in assemblies in a coming phase. So this workaround is no longer necessary, and even if it were, using "== Title" as the workaround seems worse than the minor glitch it's intended to replace and is not advisable anyway, for the reasons that follow.
• Nesting scalability: With "== Procedure", "== Prerequisites", etc., these headings vary based on the level of heading/offset of the section they're in and are not very scalable in nested content. It might look fine if it's section is H1 or H2 but if you have a "== Procedure" in a section that is an H3 in an assembly, or heaven forbid, H4, it gets ugly fast. Even despite the size issue, the fact that it varies based on where it falls is undesirable. Whereas ".Procedure" is fairly stable and more consistent throughout, despite the slight size difference at times due to tooling (better slight than drastic). For an example, see this short Entando doc preview and skim the "Prerequisite" and "Procedure" headings at each nested section. This document uses "== Procedure", which varies and shrinks in a distracting and unpleasant way.
• Conceptual/semantic clarity: As someone pointed out before, "== Title" is a section heading while ".Title" is a label. Procedures, prerequisites, and additional resources, in a modular environment, are more labels than headings imo, especially since they're repeated consistently across differently headed sections. Anything that is a heading really ought to be standalone when possible, except for genuine sub-headings in concepts and refs, but never procedures (according to the proscription). Specifics aside, I think we can agree that there is a difference between content headed "Guided decision tables" (clearly a heading) and "Procedure" (what I'd consider a label)
• Exception for "== Additional resources" in assemblies: Temporarily, the only exception to returning to block headings for procedures, etc., is for additional resources in assemblies, which should be a non-discrete "== Additional resources". The reason is that tooling will have the block label optimized for modules in Phase 1, but for assemblies in a future phase. Therefore, because includes come between the assembly title and the additional resources, it should be a genuine sub-heading and show up in the TOC (non-discrete). Prerequisites in assemblies, however, are no exception and should follow the same standard as in modules.

Links:

• Updated templates preview
• Updated Mod Doc Ref Guide preview

[sterobin]

@ChristyWatkins, @emmurphy1, just tagging you here fyi.

[sterobin]

@rkratky, @ChristyWatkins, @tradej, @asteflova, @agunn, now is probably the time decide on this before we start into the Phase 1 module reviews. It will be hard to ensure consistency in mod doc standards applied in Phase 1 if the review board is not on the same page with headings. I know it's not just me since several others on the board also agree with the proposed change/reversion. If we'd prefer to just leave things as they are for now, I believe making this change later will be even harder, because the H2 heading question affects how a lot of docs are structured, which would need to be manually addressed by writers, and because whatever we prescribe in our reviews would need to be (or should be) all the other docs for each team. And in this case, it would not be a mass-replace tweak easily applied later.

It's up to you all, of course, and I will follow orders, but am bringing it up so that we know the repercussions of postponing this.

[tradej]

Hi, I don't feel strongly one way or another, so the changes can go in as far as I am concerned.

I did just change all labels to the subheadings in the RHOAR documentation, but it took me about 5 minutes to do it with a script, and it will take approximately as much time to change them back, so no problem.

[ritz303]

@sterobin : I think you (along with others), makes some very valid points, so I'm onboard with this change. ACK.

[sterobin]

So can we merge this then? We have @ritz303, @tradej, and @lbailey (don't see her comment anymore though), and @rkratky and @bhardesty via email, who are on board or have no particular preference. Does anyone else need to sign off for us to merge this? @asteflova? We should probably merge asap before people start reviewing modules for this Thursday's first Module Review Board meeting (July 19). Otherwise reviewers will be prescribing the incorrect heading styles to modules in those reviews.