Issues with the assembly-level prerequisites heading

[rolfedh]

This issue originated in #97 but deserves its own separate issue.

After discussing this with @kalexand-rh, I have a better understanding of the item @ncbaratta mentioned. Although it deserves fuller discussion, here is the issue in summary:

Currently, .Prerequisite appears in both TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc and TEMPLATE_PROCEDURE_doing-one-procedure.adoc.

The problem is that, in TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc, .Prerequisite is inconsistent with == Additional resources (or Next steps).

Changing .Prerequisites to == Prerequisites would do the following:

• Eliminate a style inconsistency.
• Make it clear that the prerequisites apply to all of the modules, not just the first one. (With .Prerequisites, it's unclear what the scope of the prerequisites is. One possible interpretation is that it applies only to the first module instead of all of them.)
• Enable "Prerequisites" for assemblies near the top of the content hierarchy to show up in the TOC.

Issue #97 also discusses arguments against making this change. I thought it would be important to take a more complete look at the proposed change so we could have a more nuanced discussion of its benefits and drawbacks. I'll be glad to describe the issue in more detail at an upcoming meeting.

For an example of what the current assembly-level .Prerequisites looks like in our documentation, please see: https://docs.openshift.com/container-platform/4.5/installing/installing_aws/installing-aws-default.html

[yzimmerm]

I think that the 'inconsistency' here is a feature, not a bug. The Prerequisites are an integral part of any assembly. The Additional resources is an add-on that is not integral to the assembly. Therefore, it is preferable to me to keep them at separate levels.

[rolfedh]

The important and required nature of assembly-level Prerequisites is why they should be promoted to == Prerequisites instead of demoted to .Prerequisites.

[yzimmerm]

But I feel that they should be part of the introduction to the assembly, not a separate heading.

[rolfedh]

I understand. With assembly prerequisites as == Prerequisites, they are still up there in the same location; they're just easier to distinguish from module prerequisites.

[emmurphy1]

@benradey the proposal is to change the assembly template from a label (.Prerequisites) to a heading ( == Prerequisites) so that assembly-level prerequisites will appear in the TOC. This change is proposed for the assembly template only. Modules will still use the label (.Prerequisites). Will this cause an issue with PV2? We already have a == heading in the assembly template (== Additional resources). Most attendees at the review board were in favor of this change.

[rolfedh]

By the way, although I've expressed my preference, I'm not tied to a specific outcome. Rather, I'm committed to the process, which includes welcoming divergent points of view, discussing the benefits and drawbacks, and trusting the team to make a good decision by consensus. At this stage, we need to invite former commentators from issue #97 to share their points of view on this proposed change:
@kalexand-rh @ncbaratta @mjahoda @bobjohnsrh - Would you like to comment on this proposed change?

[benradey]

@emmurphy1 I don't think it will cause an issue. I assume the TOC you're talking about is the in-document TOC. This should not impact the TOC displayed in the customer portal.

[Preeticp]

Moving the discussion from: #97 (comment)

Another point that came up within the OpenShift team discussion was if we want to use Prerequisites as second level headings (==) instead of the .Prerequisites we use currently. @kalexand-rh could probably provide more context on this.

I would be very against this, mainly because we have so much of our documentation modularized already with the label format instead of the heading format and it would require extensive edits to make us all consistent this late in the game.

@ncbaratta as mentioned above, we are only talking about changing to heading format in Assemblies and not modules. This would help to:

• Keep it in confirmation with the == Additional resources used in assemblies
• Make it clear to the end user that these prerequisites apply to the entire assembly instead of the first procedural module include
• Enable these prerequisites to appear in the TOC

I understand this would cause another round of edits, but if it helps the end user understand better, the team feels it should be a recommend practice. Do let us know your thoughts, please.

[ncbaratta]

I'd like to remind everyone that even running a script requires a certain amount of human intervention in the form of checking things, etc., and is this really the best use of our very limited writer resources that we have on many programs. A decision was made to use labels and we should stick to that and not keep making changes.

[Preeticp]

From an accessibility perspective, I would recommend against using a second-level heading for prerequisites.
Users on screenreaders often browse pages from heading to heading, and the heading level is meaningful in establishing the organization of the document. The second-level heading approach would always define the Prerequisites at the same level, regardless of the location of the containing module. The screen reader user would thus lose the context of the heading, and it would no longer be clear that the prerequisites are part of the module. Navigation of the headings would also be disrupted.

@bobjohnsrh here is an example of what we are proposing.
https://docs.openshift.com/container-platform/4.5/installing/installing_aws/installing-aws-default.html

Also wanted to add that changing to == Prerequisites in the assemblies only, would make it consistent with the == Next steps and the == Additional resources sections used in assemblies.
For modules we continue to retain .Prerequisites, .Additional resources or .Next steps syntax.

Do you still think this would hamper accessibility?

[bobjohnsrh]

That is clearer, and in terms of accessibility, less of a concern.

[Preeticp]

@ncbaratta We understand your concerns. Would it help if we provided an automated way of converting this in one go? @rkratky has offered help on this, if required.

[emmurphy1]

In the Assembly Templates meeting today, Dawn Aly confirmed that if we do make this change, the == Prerequisites heading will not appear in the 'TOC' for the assembly in the PV2 Customer Portal. This is also true for == Additional Resources in assemblies and any other glue text heading. My understanding is that the UXD team recommended that only modules appear in the TOC in the Customer Portal. While this won't break anything, it might defeat the purpose of the change. AFAIK, == Prerequisites in the assembly will appear in the PDF TOC.

[rolfedh]

I'm concerned that PV2 suppressing == H2's in assembly files (but not the equivalent headings from modules) is going to be a problem.

A quick inspection of the OpenShift doc shows that many assemblies contain == H2's for ordinary headings, not just for the standard Prerequisites and Next Steps. For an example of just one file, please have a look at installing/installing_gcp/installing-restricted-networks-gcp.adoc.

This means that suppressing == H2's in assemblies would create serious gaps in many ToCs. To work around this might require creating many new files (sub-assemblies/modules?) to serve primarily as containers of links. I'm not sure that's the desired outcome.

Dawn, @adahms, Wouldn't it make more sense for PV2 to render == H2's in assembly files?

[VladimirSlavik]

Did the discussion involve also the [discrete] thing? I do not see it mentioned anywhere...

[rolfedh]

Did the discussion involve also the [discrete] thing? I do not see it mentioned anywhere...

I don't fully understand the discrete headings conversation. (For more details, see https://asciidoctor.org/docs/user-manual/#discrete-headings.) @bobjohnsrh mentioned them in issue #97 before we transferred that part of conversation here to issue #124. More recently, above, Bob mentioned:

That is clearer, and in terms of accessibility, less of a concern.

So I think it's okay.

[Preeticp]

A quick inspection of the OpenShift doc shows that many assemblies contain == H2's for ordinary headings, not just for the standard Prerequisites and Next Steps. For an example of just one file, please have a look at installing/installing_gcp/installing-restricted-networks-gcp.adoc.

This means that suppressing == H2's in assemblies would create serious gaps in many ToCs.

A huge +1 to what @rolfedh mentions. This is a serious concern.

[VladimirSlavik]

So, I have not been involved in this for more than a year, but... Plain asciidoctor adds == H2s to ToC, and does not if they are prepended with [discrete]. Which is just what you want, I think? To keep control over what happens in writer's hands. That this could be disputed sounds very strange to me; there must be some misunderstanding.

[Preeticp]

Hi @VladimirSlavik apart from adding it to the TOC, the main focus is on using the == Prerequisites syntax for Prerequisites in the Assembly and retaining the .Prerequisites syntax in the modules. This would make it at the same heading level as Next Steps/Additional Resources in the Assembly.