Cross-referencing between modules should not be done within modules

[gsheldon]

Hi everyone,

I'm currently in the process of putting together a user story that is predominantly made up of modules from a number of user stories. The biggest issue I'm having by far is reusing modules that link to other modules.

When a cross-reference (xref) exists that points to another module, I have two options:

1. I can use conditionals to remove that link from my particular user story.
2. I can pull in the module that it links to.

The second option tends to create a cascade effect of pulling in more and more content that might only be vaguely related to the user story I'm trying to create.

The first option can result in spaghetti code and possibly break other stories, particularly where assemblies are included within other assemblies. It also doesn't really scale when we think about reuse across products and all possible user stories.

The current modular docs templates, as well as the Modular Documentation Reference Guide, advise including links to additional resources closely related to the contents of the module ("other documentation resources (such as assemblies or modules)..") within the module.

I am proposing that instead of providing cross-references to other modules within modules, they should only be added to the assembly file(main.adoc). Doing this results in the link only appearing in the assembly where the linked module already exists and allows more flexible module reuse across multiple assemblies without needing to add conditionals everywhere.

For example:

include::product-migration-guide/migration-configure-kie-server-proc.adoc[leveloffset=+1]
For information about installing {PRODUCT} on {EAP_LONG}, see xref:eap-dm-install-pro[].

renders the following sentence as though it were a part of the preceding module:
"For information about installing Red Hat Process Automation Manager on Red Hat JBoss Enterprise Application Platform, see Installing Business Central from the ZIP file "

TL;DR - We should only be cross-referencing between modules in the actual assembly files, rather than in modules themselves to make module reuse more flexible.

[VladimirSlavik]

The result for user (reader) would be: Read about a thing, scroll back somewhere to get the actual link to stuff that is in the same document. Doesn't sound like an improvement to me?

(The module library should solve exactly that. Make a reference to a module, automagically get a working link to it. Of course, that is just a plan now...)

[gsheldon]

@VladimirSlavik sorry my first example was unclear as it wasn't linking an actual module, it was just an example I had on hand to show that it rendered the way I expected it to. I've modified it in the original comment.

How will the module library address links that go to modules that aren't necessarily relevant to the user story? Will it just pull that module into the build? What about modules that are linked within the linked module?

[vikram-redhat]

Hey @gsheldon - the MVP states that modules must not include xrefs. Only assemblies can have xrefs.

[gsheldon]

@vikram-redhat I've linked in the original comment where the Modular Documentation Reference Guide states under Procedure Additional Resources:

Additional resources list links to other material closely related to the contents of the procedure module: other documentation resources (such as assemblies or modules), instructional videos, labs, and similar resources.

The linked template also states:

A bulleted list of links to other material closely related to the contents of the procedure module.

I haven't found anywhere that specifically says not to include xrefs (or any other way of linking modules) in modules. It's certainly fairly standard on our product to include links to other modules within modules, which is why I'm raising the issue.

[bhardesty]

@gsheldon it might be helpful to see an example of what you're trying to do. Practically speaking (though not necessarily reflected in the mod docs guide), I would say that additional resources for modules should be fairly rare. Nonetheless, if you do include any xrefs to other modules (as additional resources), they should make sense for any context in which the module might be used. Otherwise, the module isn't truly an independent module.

[vikram-redhat]

Hey @bhardesty - as I had mentioned in my previous comment, xrefs are not to be used within modules as per MVP. I haven't linked to the MVP requirements here, but if you search for it in the FCC mojo page, you will see it.

This is another thing that I think should be communicated more and is going to cause a lot of issues if we don't standardize and update the mod docs guide. This current iteration of mod docs guide is out of sync with the FCC requirements.

[vidya-iyengar]

Thanks for bringing this up @gsheldon.
Do we have a strong use case where xrefs included in a module makes more sense than having them included in the assemblies?
I think this would depend on the specific case where we need to decide if it is worth compromising and having the xref inside the module.

[bhardesty]

@vikram-redhat, I've been equating MVP with Phase 1 of FCC, in which only a small number of products are participating. Is this not correct? If the MVP applies to everyone, then it really needs to allow for includes within modules (and possibly xrefs as well). Since I work upstream-first, I use includes at the module level to inject content that is upstream-only. Without this ability, I wouldn't be able to reuse a number of modules in the downstream doc.

[vikram-redhat]

@bhardesty - I am not making the decisions on it. I am just letting this thread know the decision. :)

Having said that, I don't know if the decision will stick post the MVP.

[ChristyWatkins]

Notes from meeting with Tooling:

• xrefs are NOT supported in phase 1.

• We should limit the usage. How can we define that best practice for limiting the usage for teams going forward? If you’re modularizing existing content, limit (or remove) the ones you’re modularizing.
  If you include them, they will work for now, but they may have to change in the future.

• Need to define the different link cases and how that link should be coded to make things clearer in the reference guide.