Removing or discouraging Additional resources in assemblies

[mjahoda]

We should consider either removing Additional resources from the assembly template or at least discouraging using it directly in an assembly especially when the last module included in the assembly contains its Additional resources, too.

It looks nasty at best, it might be confusing at worst.

An example: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html-single/security_hardening/index#additional-resources_configuring-automated-unlocking-of-encrypted-volumes-using-policy-based-decryption

[jherrman]

+1

In my experience, Additional resources added to an assembly are usually more appropriate for one of the modules in the assembly anyway, so discouraging their use would be ideal, AFAICT.

[jafiala]

+1. I think I've even seen a triple Additional resources section once, because of a nested assembly.

[emmurphy1]

I disagree. Additional Resources at the assembly level is the place to put additional resources that relate to the entire assembly. Or it can be renamed Next Steps to lead the reader to further options. The example that you give, @mjahoda, is a sub-assembly. I can see your point, however, I think this is a case where we should leave it up to the discretion of the writer. BTW, some writers prefer to put all of the additional resources for a user story in the assembly Additional Resources. You might argue that the resources would be better located with the associated modules. But what if the resource is appropriate for multiple modules in a user story? If we do away with assembly level Additional Resources, then will we be forced to have the resources repeated throughout the user story, in each module? I think we should leave the Additional Resources in the the templates and let writers decide how best to use them.

[soulcharmer]

+1, I believe we should have clearer recommendations of how to use Add. resources sections to prevent situations outlined in the OP. Maybe as a part of peer review guidelines if nothing else.

[jherrman]

BTW, some writers prefer to put all of the additional resources for a user story in the assembly Additional Resources. You might argue that the resources would be better located with the associated modules.

Exactly. If we want to refer the reader to a resource that is connected to, say, a specific procedure, they're very likely to miss the link entirely if it's instead appended at the very end of the assembly (i.e. several sections later). I can see the argument for not repeating resource links that apply to the entire assembly, but bunching up all the sources on the assembly level feels like a very unfortunate way to go.

But what if the resource is appropriate for multiple modules in a user story? If we do away with assembly level Additional Resources, then will we be forced to have the resources repeated throughout the user story, in each module?

That to me seems like the lesser of the two evils here, yes.

[ndeevy]

+1 to avoiding the bunching up effect shown above. Even if only advising caution around assembly-level Add Resources. It looks low quality or like it happened by some accidental glitch. To @jherrman's lesser evils point: +1, repeating on a module level might not be the worst option (if they are truly relevant to each module) if modules should be able to stand on their own.

Somewhat affecting this issue is what I consider to be overuse of the Add Resources section. Sometimes that section seems populated just for the sake of filling in the template without assessing whether the resources are actually necessary. The templates say "**Optional. Delete if not used.

• A bulleted list of links to other closely-related material**" but I suspect people often include it +links by default. We should instead aim to keep links to a minimum and use only when necessary (because they can distract and send readers down a link rabbit hole, not to mention the maintenance overhead they introduce).

Maybe the templates could include some extra guidance or like @soulcharmer said, maybe guidance in the peer review guidelines would be wise. The supplementary style guide might be another possibility.

[ryandeussing]

some writers prefer to put all of the additional resources for a user story in the assembly Additional Resources

That strikes me as a hack one might employ to structure the assembly in question 'just so'.

But that runs counter to the goal of modularization, which is to remove the 1:1 relationship between a solution and ~the~ one assembly or title in which it may be published.

I think modularization demands that the additional resources should be repeated in each module - so when any module is included elsewhere, it leaves nothing useful out.

And that's why additional resources should be used sparingly, to avoid unnecessary repetition.

[emmurphy1]

There is always a trade-off between making sure that module content is standalone and avoiding tedious repetition throughout a user story. The same problem occurs with acronyms and initialisms. Do we define on first use in the user story or do we define in every module? Do we include the product name in every module? As far as Additional Resources go, I think the problem occurs mainly with sub-assemblies. I agree that we need to add more guidance about how to use them.

[mjahoda]

From the mod-docs perspective, resolved by https://github.com/redhat-documentation/modular-docs/pull/210

However, we believe that the problem should be addressed also on the webdesign level: https://issues.redhat.com/browse/DOCS-111