Remove "// Module included in the following assemblies section"?

[rolfedh]

I see an opportunity to optimize/simplify the templates and reduce writers' efforts by removing the // Module included in the following assemblies section at the top of each template file.

Why? This information is redundant and sometimes inaccurate. We have several ways to get current and accurate information, including:

• Using Pantheon 2 to see which assemblies include a file.
• Using the script developed by Paul Needle to generate this information.
• Using the search feature in Atom and other text editors. You can search any project or directory for the include: statement followed by the file path.

The ease and accuracy of these methods outweigh the drawbacks of maintaining the same information manually.

I’d like to hear your thoughts on this.

[pneedle-rh]

The script that lists the assemblies used by a particular module was introduced into the openshift-docs repository through PR 28337 and can be found here. The script was also cherry picked to enterprise-4.4, enterprise-4.5, enterprise-4.6 and enterprise-4.7.

You can start the script from the top level directory in your openshift-docs local clone by running ./scripts/list_assemblies_used_by_modules.sh. Then, follow the prompts to run it for a single module or for all modules that are updated in a Git commit.

[sterobin]

@rolfedh I don't know if the answer to the issue is to remove it because either way, I believe one of the scripts out there (can't remember whether @pneedle-rh 's listing, @fbolton's Nebel, or @mrksu 's new doc) actually adds exactly that content to the top of reused modules. If that's the case, then keeping this in the module template would be consistent with whoever is doing this either automatically or dynamically. I don't really have a strong feeling either way, and definitely see the maintainability issues especially in large projects, but I suppose I'm just mentioning the other side of the argument. I support whatever decision the group makes on this.

[pneedle-rh]

@rolfedh I don't know if the answer to the issue is to remove it because either way, I believe one of the scripts out there (can't remember whether @pneedle-rh 's listing, @fbolton's Nabel, or @mrksu 's new doc) actually adds exactly that content to the top of reused modules. If that's the case, then keeping this in the module template would be consistent with whoever is doing this either automatically or dynamically. I don't really have a strong feeling either way, and definitely see the maintainability issues especially in large projects, but I suppose I'm just mentioning the other side of the argument. I support whatever decision the group makes on this.

@sterobin hi! The script that I created does not update any modules. It queries by using grep and then provides a formatted output to stdout. That information can then be used to manually update the assembly references at the top of module files, if necessary.

[rolfedh]

Thanks for sharing these insights. I'll also bring this proposal up in our upcoming Mod Docs Review Board and Steering Committee meetings so there will be plenty of opportunity to discuss it.

[VladimirSlavik]

I have never seen this comment list actually used. Maybe twice, and then the information was already outdated. Just cruft to skip when reading the module source.

[msuchane]

@rolfedh, I agree that we should remove the "included in" section from the templates. As @VladimirSlavik says, I've rarely seen it used at all, and when it is used, there's a high chance that the information is outdated so you'd have to check for yourself anyway.

@sterobin, my newdoc tool just creates the empty section. It doesn't try to populate or maintain it in any way.

[sterobin]

@pneedle-rh , @VladimirSlavik , @mrksu ack, thanks for clarifying. So @rolfedh whatever the group decides then. Thanks.

[fbolton]

@sterobin Nebel has a command that can add this kind of metadata to your modules (nebel update --parent-assemblies).

In the meantime, it has occurred to me that it would probably be more useful to provide a utility that opens a module in your favourite text editor, and automatically opens the associated parent assembly and sibling modules. That would make it easy to edit a module in the context of the surrounding content. I think that is probably the main reason why you would want to know what the parent assembly is in the first place.

[sterobin]

@fbolton I see, very good. Yes, that would be outstanding. Thanks for the info, Fintan.

[emmurphy1]

@rolfedh it might be good to bring this up at the steering committee meeting - summarize the conclusions here and see how folks feel about removing?

[rolfedh]

At the steering committee, a significant number of participants supported removing "// Module included in the following assemblies" section. No one spoke in favor of preserving it. We also discussed/proposed updating the Mod Docs Reference Guide to state that:

• This section is no longer required.
• Removing it is optional (no harm in keeping it).

I would also mention the alternatives, which include:

• In PV2 will list the assemblies that include any given file.
• Searching your repo for the filepath.
• Running the script that demonstrated recently.

[rolfedh]

@pneedle-rh @sterobin @emmurphy1 @VladimirSlavik @mrksu @fbolton Please review and approve the PR https://github.com/redhat-documentation/modular-docs/pull/154 for this issue.

[rolfedh]

/close