Add official guidance around designating module types

[adahms]

The tooling team, in consultation with CCS, has implemented two methods for defining module type in modules, as follows -

Add the following attributes at the top of the file directly under the title, with no spaces -

:pantheon-module-type: CONCEPT :pantheon-module-type: PROCEDURE :pantheon-module-type: REFERENCE

Prefix the module file name with one of the following -

concept: con*.adoc procedure: proc.adoc reference: ref_.adoc

Either method is valid, but these requirements should be noted in the documentation as part of the module characteristics.

[ncbaratta]

Does the underscore in the filename matter? Is it okay if it's a dash? The old guidelines were for a dash, which is why I ask.

[emmurphy1]

This is a very good point. in the examples above, the prefix is following by an underscore. There was a discussion some time ago about whether to use an underscore or hyphen to separate words in module file names and I believe we agreed to go with hyphens. The reason is that if we make the module ID match the file name, then when an assembly renders and the assembly context is appended, if we use all hyphens it is difficult to see what the module name and what the story name is in the URL, for example: proc_running_installer_install-on-eap vs proc-running-installer_install-on-eap

In these examples, proc-running-installer is the module file name and _install-on-EAP is the assembly name.

I confirmed with Ben Radey in tooling that they don't care whether we use hyphens or underscores in the file names as long as we standardize on one way so they know what to expect. I vote for hyphens for the reasons above. I know that different groups have all sorts of naming conventions that will have to be reconciled eventually so what ever we decide will be a pain point for some groups.

[bhardesty]

@adahms is there a place where I can raise an issue about the module type attribute name? The "pantheon" prefix refers to a Red Hat internal system, so it could be problematic to use it in upstream projects.

[adahms]

@ncbaratta, @emmurphy1 - yes, the underscore in the file name matters. I recall the discussion where we discussed the underscore-versus-hyphen challenge as well, and agree with your concerns.

@emmurphy1, @bhardesty - Emily has recently been involved in some discussions with Ben Radey and the tooling team, and I would recommend raising the issue with her so that it can be brought forward to the tooling team and discussed. As a preliminary discussion before that, it might be helpful to collect together some people interested in this to come up with a CCS-wide recommendation and see whether that can be adopted.

[emmurphy1]

@adahms , @ncbaratta I had a chat with @bradey yesterday. My understanding is that for tooling whether we use hyphens or underscores doesn't matter to them, except that they would like us to standardize so the tools know what to expect. I believe this has been discussed in this forum and we agreed to use hyphens in file names. So unless anyone disagrees, I suggest that we formalize this standard in the templates and the reference guide. At the same time we can add the directive to specify module type outlined above.

[sterobin]

All, +1 to using all hyphens in file names, so that we can use an underscore with _{context} in anchor names to achieve the module vs assembly distinction in URLs and in cross refs that @emmurphy1 describes: proc-module-name_assembly-name. I thought this was decided long ago, after much back-and-forth. If tooling doesn't care, then I vote we go with all-hyphened file names and move forward.

[ncbaratta]

+1 for consistency, I'm not picking on which it is :)

[adahms]

Great point, @emmurphy1 - good decision and discussion here, and +1 from me as well.

[ncbaratta]

So, just to confirm what I should be telling my teams. Should everyone have dash versus underscore? Or does each project just have to be consistent within that project?

[sterobin]

@ncbaratta , consistent across all products/projects is the goal, from what I understand. So requiring all dashes in file names and suggesting _{context} in anchor names as the way forward, imo. This convo will probably never end, so I suggest we just make this the decision and move forward. If people choose to disregard, there's not much we can do about that, other than say, this is the way. People have their agency I suppose, as with anything.

@adahms , @emmurphy1 ^^ Wdyt?

[ncbaratta]

Yes, I'd love a declaration of what to do :) I don't care either way, but I already shared the original issue here where it said underscores and so I have writers working on making those changes - I'd like to get everyone on the same page and prevent extra work.

[adahms]

@sterobin @emmurphy1 @ncbaratta - An end to this conversation will be in sight once we start using the new system and we all need to follow the standard approach we define or our modules don't go in. :)

In all seriousness, though - I agree with the approach proposed to start using hyphens in file names and maintain underscores in context IDs. My one caveat would be that it would be good to get an official 'ok, we'll make that change' from the tooling team before going out and making changes just to be sure, then send out a broadcast to all teams to let them know about this change and the reasons for its adoption.

[VladimirSlavik]

As one of the known complainers, I think this is ok :) There's no technical issue I can see about this...

[bobjohnsrh]

I have a couple of observations based my experience leading leading a couple of conversions from unstructured content to DITA (Darwin Information Typing Architecture).

I recommend using the prefixes even if you use the attributes. Even though DITA topics are natively typed within the content, information typing prefixes on DITA topic file names are incredibly useful. Prefixes make it very easy to sort and navigate content, especially when you do not have a content management system. Moreover, the prefix makes it easy to tell the information type of the module. Often, you cannot tell type of the module simply from the title; concept modules and reference modules are particularly difficult to differentiate based on title. I always included information typing prefixes in file naming schemes.

I'll add my weight to those advocating for using hyphens or dashes in the file names. I always used these characters in my file naming schemes, and never considered underscores. I never saw a need to differentiate the prefix from the rest of the file name, and no one ever had any difficulty working with the files. The underscore character never added enough value that it was worth the awkwardness it added to the file name.

[ncbaratta]

I'd like to see this get into the guide ASAP. We have communities reading these guidelines and for some reason, I thought file naming was in this guide and it's not.

[adahms]

@ncbaratta - thanks for the push; quick question as follows.

@ncbaratta @emmurphy1 @bhardesty @sterobin - Given the discussion above, I have raised a tracker for the tooling team to change this from an underscore to a hyphen for us. Until that change goes through, of course, underscores will still be the requirement.

Would there be any issues in documenting our future intent and getting everyone to move towards that? I don't think any of the teams who need to commit to underscores right now will be largely affected, and hyphens should be what we need by the time we start using the tooling more fully.

[ncbaratta]

I think documenting our future intent is A-OK since the tools aren't in place yet and having it as an underscore now won't stop the docs from being processed.

[sterobin]

@adahms @ncbaratta , +1. So are we saying then to go forward with hyphens in what we're actually doing or not? I see Andrew says that until tooling team commits, underscores is the requirement, yet we're talking about documenting as hyphens as we've discussed to get people moving toward it. I'm documenting a new product that is going to Dev Preview next Weds, so finalizing everything this week, and I've been using the proc_ until I got word here that we are good to use hyphens. So which should I use today?

[adahms]

Thanks @ncbaratta!

@sterobin - Technically speaking, unless you're publishing content through the new software, it doesn't matter whether you use underscores or hyphens at this stage. The reason I am asking is because I am wary of asking teams to do anything that would involve re-work (i.e. using underscores because that's what we have now only to come back and change them all to hyphens when the change goes through) and I'd like to get a sense of appetite for risk and change.

If you're using underscores for your release, that won't be a problem, and I would recommend following that to avoid any last-minute changes.

In terms of what we add to the actual documentation, however, my recommendation is that we document intent, as Nicole called out, so that we can get teams moving towards the official end goal.

Are there any issues with that?

[sterobin]

@adahms , I'd prefer to switch to the hyphens, as I was a big advocate for that. The only issue I see for me is that now is the perfect time for me to switch from underscores to hyphens, before we publish all content for this new product at the end of the week up to next Weds. Right now, I can swap them all out and won't impact anyone else. If I wait to do it, then I'll have to work with our community side to update website hyperlinks (which will be static at first). So ideally, I suppose switching to hyphens now would be best, but what are the odds looking like right now that it won't work and will have to be underscores? So I can weigh the risk.

[adahms]

Thanks for the additional notes, @sterobin.

I'll pass on the issue where this is being tracked elsewhere, but an official request has been made to change the separator from underscores to hyphens, and I have spoken to Dawn about it as well.

As such, I have full expectations that it will go in this direction.

[sterobin]

K @adahms , I think I'll roll up to hyphens then. Thanks.

[vikram-redhat]

I know this issue hasn't closed yet so want to make two notes:

1. Was there a decision made for those who don't want to change the files names and who want to go with the attribute option? @bhardesty had raised the point that using "pantheon" as a part of the attribute name would be limiting and I agree. So, would the guideline be to use "module-type"?

2. The current guideline says: "Give the module file the same name as the anchor used in it " (https://redhat-documentation.github.io/modular-docs/#anchor-and-file-names). I am assuming that those who go the route of changing the file names to denote module type, don't need to change their anchors as well. If that is the case, when we make this issue changes official we should change that language as well. If not, then we should guide those teams to rename their anchors when they change their file names.

[theashiot]

If I'm not too late, my thoughts on this, considering practical implications:

Risk: Different teams have adopted different conventions for file-names. For each team to comply with the specification that is decided here will require a lot of work.

Mitigation:

IF whether we use a hyphen or underscore is a matter of opinion AND not a technical requirement, THEN I suggest we adopt the style that is most prevalent. For instance, if 1000 modules across products use _ and 500 modules use -, then it makes more sense to update 500 than 1000. (Same for anchor IDs)

Furthermore, in future

Risk: Specifications can and will change.

Mitigation:

• State that whatever specification is described in the official guide is the only one supported.
• What "supported" specification means is that whenever a specification is changed, the mod-docs team will provide the documentation teams with the tools to transition to the new spec - for instance scripts to automatically change the file names, anchors etc.

best, ashwin

[ncbaratta]

@ncbaratta @emmurphy1 @bhardesty @sterobin - Given the discussion above, I have raised a tracker for the tooling team to change this from an underscore to a hyphen for us. Until that change goes through, of course, underscores will still be the requirement.

Can you provide us with the issue number so we can track what's being discussed there?

[emmurphy1]

This issue was resolved in https://github.com/redhat-documentation/modular-docs/pull/121 and the changes incorporated in the Reference Manual.

@adahms we need to document variables as an alternative to following the file naming conventions in the Pantheon 2 user guide. The file naming conventions are recommendations in the Reference Manual and the requirement to use the variables if uses do not follow the file naming recommendations is only relevant to Pantheon 2 users.