search

redhat-documentation / modular-docs

Modular Documentation Project provides guidelines and examples for writing technical documentation using a modular framework.
Creative Commons Attribution Share Alike 4.0 International
82 stars 68 forks source link

Issues with the assembly-level prerequisites heading #124

Closed rolfedh closed 4 years ago

rolfedh commented 4 years ago

This issue originated in https://github.com/redhat-documentation/modular-docs/issues/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:

Issue https://github.com/redhat-documentation/modular-docs/issues/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 commented 4 years ago

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 commented 4 years ago

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

yzimmerm commented 4 years ago

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

rolfedh commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

Moving the discussion from: https://github.com/redhat-documentation/modular-docs/issues/97#issuecomment-669257437

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:

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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

Preeticp commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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

rolfedh commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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.