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
80 stars 67 forks source link

Pantheon 2 creates its own labels for "Additional resources" in modules vs assemblies. That should be dealt with here. #158

Closed stoobie closed 3 years ago

stoobie commented 3 years ago

Previously, Pantheon 2 didn’t distinguish between additional resources sections for modules and assemblies as clearly as it could have, creating some confusion among readers. Engineering has now improved the appearance of these sections to delineate them as seen in the following assembly: https://access.redhat.com/documentation/en-us/red_hat_openshift_api_management/1/guide/53dfb804-2038-4545-b917-2cb01a09ef98

So now for modules we have by default .Additional resources is hidden and you see a link to show it: image

And when you expand it you get this:

image

And for assemblies we have this (expanded by default):

image

First of all, Content related to this topic|guide and Additional resources together is redundant and a bit confusing.

Secondly, I propose that we adopt the new wording in place of Additional resources and instead use something like Content related to this topic for modules and Content related to this guide|section for top-level assemblies|nested assemblies.

stoobie commented 3 years ago

The wording for assemblies is tricky, because an assembly can be either a guide or a section within a guide, so you can't always say Content related to this guide.

emmurphy1 commented 3 years ago

@stoobie, Additional resources can be Next steps, or some other label that the writer determines. Therefore, having the label under Content related to this topic/guide makes sense. We discussed it at the Modular Documentation Review Board and unanimously decided against this change.

stoobie commented 3 years ago

@emmurphy1 OK, so closing the issue.