Allowed to xref within a module?

[bergerhoffer]

Question. Does the current "Do not include xref links in modules." direction only apply to cross referencing other modules, or is it a complete ban on xref links in modules?

I ask because I'm wondering whether it's allowed to xref to a section further down in the same module. Thanks!

[adahms]

Hi @bergerhoffer - good question.

As of this moment, "Do not include xref links in modules" does indeed mean a complete ban on xref links in modules. A good rule of thumb in our current state is that you should be able to run the 'asciidoctor' command on an individual module file and have it compile into correct output without any issues, so anything that comes in the way of that is a challenge.

That said, the tooling team is aware of the need to provide some support for this, and is working on methods to enable it. I have a few suggestions on how to work with this and ways to structure content as well, so if this is going to be an issue for your team, please let me know and I'd love to have a chat and see if there's anything we can do.

[bergerhoffer]

Hi @adahms, thanks for the response. Just to make sure that we're on the same page - your test of running asciidoctor on the single module would still work just fine for what I'm asking. Because the xref isn't to another module - it's to a place elsewhere within the same module. So does your answer still stand as a complete ban?

And I am aware of the tooling team's plans to provide support for xrefs eventually (yay!), so this question is just for in the meantime. Thanks!

[adahms]

@bergerhoffer - from a purely technical perspective, xrefs from one point inside a module to another are supported.

As a general use case, however, I would be curious to understand more about why such a strategy might be necessary. Ideally, modules should be written so that relevant content is provided in the order it is needed, although I'll be the first to admit I doubt I know all the possible use cases, so I'd love to understand more about the need here so that it can be incorporated into future planning as well.

[VladimirSlavik]

Sorry to digress, but ...

Ideally, modules should be written so that relevant content is provided in the order it is needed

In my experience, increasing complexity of the text topic can erode this assumption until it fails: One can never make modules "support each other" this way, if there are too many conflicting constraints. Then the matter seems easily resolved with links to the rest of information - and in case it's within the same document, making and validating a xref is just easier.

As a real example from RHEL: The installer can run as-is. But some customers have a specialized networking hardware that needs drivers and configuration. So they must have these, interrupt the boot process, and type it in all manually. So there are the topics of "Making a driver disk available", "Creating a driver disk", and "Using a driver disk", which are procedures for an entirely different set of tools, each. Actually "making X available to the installer" is a common enough theme that there is significant duplication in the content. So there's at least one place to link to, and it will be within the same document. But wait - this is not over yet! How does the user configure the network from there - link to networking docs, and the configuration is passed to/via kernel, so there goes another document to be linked. And the user should know how this interacts with the rest of the process. Possibly another place to link, this one in the same document... And then there are at least three other ways to arrange the modules, which will yield a different set of "wants a link" places.

Maybe there's an art I did not master - arranging the information such that it works well for both the user and writer?

[bergerhoffer]

@adahms Though it does sound nice in theory to be able to provide everything in the right order, sometimes it's just not practical to. I have a Google doc that collected real examples of instances where an xref might be necessary in the middle of a module or procedure. I can always share this with you if you haven't seen it yet, if you'd like to understand a few more use cases on xrefs in general.

In the case of this GitHub issue question, I'm only asking about linking to later in the module, but the same reasons could apply. I mostly just want to know whether, in the meantime before xrefs between modules is officially supported, it's acceptable or not within the current guidelines to xref to a later point in a module.

If not, that's okay. I'm honestly more concerned with getting the xref between modules ban lifted anyways. But I'm asking because we had a few instances in our repo and were trying to determine whether it was necessary to remove them or not, to adhere to the mod docs guidelines.

[adahms]

@VladimirSlavik - thanks for the question and for the examples from RHEL.

What you're describing to me sound like individual user stories and use cases, ideally resulting in individual assemblies. I can immediately see the problem this creates in a giant proliferation of assemblies - especially in the case of RHEL - and can see how even doing so might not cover all the different possibilities you've covered.

However, what we are trying to achieve in the move to FCC is exactly this - no more monolithic installation guides with multiple different routes that link users to other guides with the required details, and more A-Z assemblies that take users through the exact steps they need at that time.

As an example from the ones you've provided, we shouldn't be linking to networking information if that's what users need to go and do right now, but actually including the modules to help them do that in the same document so that they don't need to go jumping around and come back.

Of course, this results in a certain number of specific workflows rather than covering every single possibility (what if we want custom storage, but not custom networking, for example) but this is where we are trying to understand exactly what customers are trying to do in the real world so that we don't document every possibility, and provide references as needed to those less common cases.

Long story short, we need to fix this through an understanding of customer need and gathering content to where it's immediately used first and foremost.

If there are any specific examples of where this breaks down - as I imagine there are - I'd love to take a look at that and see how it might work.

[adahms]

@bergerhoffer - yes, XREFs inside a module are supported. The only problem at current is when a module links to something outside it.

Similar to the discussion with Vladimir above, I'd love to see your Google document and review the use cases there. I suspect this will be a steady process of understanding what we can do today and whether that's something we can solve via the structure, tooling, or just accept, but until we get a good list of those and incorporate it into our software and planning, there's not much we can do to understand and tackle this as a department.

[bergerhoffer]

Thanks for clarifying @adahms. And I'll shoot you an email with that Google doc. Thanks!

[emmurphy1]

Whether or not to use xrefs is certainly a complicated and contentious issue, @bergerhoffer ! There is no technical problem using the xref: syntax if you publish on PV1 (as long as the source and target files are in the same assembly) and @benradey is working to make xrefspossible in PV2. However, whether or not you should use xrefs in modules is really a style issue so any directive about whether or not to use them belongs in the style guide. And if in the end PV2 cannot support xrefs in modules, that information should go in the PV2 user guide. Therefore, I suggest:

• Remove references such at this from the modular documentation guide: Because of current tooling limitations, you cannot include xref links to other content in your collection in the concept module. You can include xref links in the assembly that contains the concept.
• Add an issue to the style board issues about whether or not to use xrefs in modules.
• Add this as as a possible PV2 issue for the PV2 user guide.

[emmurphy1]

@bergerhoffer there is no longer a blocker to using xrefs in modules in PV2. There are some PV2-specific formatting requirments, but those belong in the PV2 User Guide. I'll work with @stoobie to make sure they are included. Therefore, I have updated the Modular Documentation Reference Guide and templates in this PR: https://github.com/redhat-documentation/modular-docs/pull/162/files