Include :_module-type: variable into the template

[Levi-Leah]

Pantheon v2 extracts some information from variables defined in the document content. These variables must be defined at the header level (not at the body level); otherwise, Pantheon v2 cannot extract them.

As of this writing, the only such variable is :_module-type:, but future development may introduce other such variables as well.

[stoobie]

I think it's a great idea to include these variables (attributes) within the templates. Pantheon 2 uses them to implement metadata within modules.

However, including these variables within the templates is not a substitute for the human-readable intuitivity of including the content type as a prefix in the file name, which enables visual parsing and file sorting to browse files in a repo.

So +1 to include the :_module_type: attribute in the templates.
In addition to using content type in the filename prefix.

[pwright]

what happens if the filename starts proc_ and the attribute value for _module_type is set to concept?

I see that the variable wins, but then the humans can't understand what's going on

[stoobie]

@pwright What do you suggest? Just using one or the other, but not both?

I understand that there's an opportunity for introducing inconsistency/bugginess by having two mechanisms.

In my mind, there are plenty of opportunities for introducing inconsistency. I worry about losing the ability to visually parse and sort files in a huge repository, sometimes within a single folder. I think it's improbable that a module's content type will change over the course of time.

[benradey]

Two thoughts...

1.) Does a module ever change from one type to another? A variable change would be easy to ingest between document versions. A file rename would be problematic.

2.) From a future-proofing standpoint, it would be easier for authors to work in the mindset of "I have several variables to set and they all live in the header" as opposed to "well one piece of metadata comes from the filename, one is set as a header variable, another is computed from the length of my abstract, and another is inferred from whether I have additional resources..." (making up examples but you see the picture of the world I'd want to avoid)

[benradey]

Third thought...

From the perspective of "keep Pantheon as flexible as possible" I would shy away from being prescriptive about what the filename ought to be. I understand we're not proposing that a filename prefix becomes a requirement, but consider a scenario of a team who is trying to bring their docs maximally into the Pantheon fold. They could be looking at one of two scenarios, either:

A.) Add an additional variable to their docs which is unlikely to affect any actual content
B.) Rename all of their modules, which is likely to involve updating all references to those modules

Option A feels less impactful, and has the added advantage that the team would be free to choose any file-naming scheme they would choose (whether it's proc/con/ref prefixing or literally anything else), and preserves Pantheon's aim of flexibility.

So, I really like the idea of the _module-type variable being the primary driver for Pantheon. And in recognition of the many teams we have today that use filename prefixing, we can also key off the filename as a secondary indicator of module type for the teams who wish to use that technique (but, again in the interest of flexibility, it is not a requirement, more of a best practice perhaps).

[stoobie]

I agree that the variable is the way to go. No argument, and for all the reasons you point out.
And I don't mean to require changing existing filenames if there's no technical reason to do so.

What I'm saying is that I still think that it's a good convention for writers to use to make filenames as useful and easy to parse as possible. I guess if you're in Pantheon and you can sort by content type, that would do the job. But if you're viewing a repo locally, you don't have that functionality, and we'll still need to maintain our own local repos, correct?

[pwright]

I agree with @benradey that a variable is the way to go.

@stoobie I see what you're saying, that it's nice to have a filename that represents the content type, but:

• do I really care about module type? you could argue that the prefix makes it harder to see what the file does, some groups used to add the type as a suffix for this reason.
• if the prefix conflicts with the variable value, the 'quick scan' will mislead the writer, and that will introduce a whole new testing requirement for consistency of prefix to variable value

I'm glad @stoobie brought up 'local development', that's what we need @benradey - not that we necessarily need to run Pantheon locally, but some of the 'pantheon logic' to run on our machine to provide a wysiwygip experience (you can work it out 😄 )

ATM our workaround is to encode that logic in directories and filenames.

[benradey]

Yes, authors will certainly always have a local authoring experience, we are not trying to supersede that with Pantheon in any way. Having said that, there are some features that Pantheon will provide that won't be able to have local analogs. (Xrefs come to mind, local preview is going to necessarily be a mixed bag there, same with cross-repo docs once we eventually get there, no way to reliably do that locally...)

If there's a local need regarding authors needing to summarily view the module type, can you help me understand what it is?

[pwright]

While I might not have @stoobie requirement for scan filenames to note module type, I would like to scan assemblies with the same notion, eg this might raise a flag with me:

include::ref_<name>[]
include::proc_<name>[]
include::proc_<name>[]
include::proc_<name>[]
include::proc_<name>[]
include::proc_<name>[]
include::proc_<name>[]
include::con_<name>[]
include::con_<name>[]
include::con_<name>[]

seems odd, right?

[emmurphy1]

We have guidance about file names in the reference document. Currently, file names have many variations between documentation groups and not all groups have the module type at the beginning of the file name, or even at all. For that reason, I like the idea of putting the module type variable in the templates. Also, as Ben points out, PV2 supports both the variable and the file name prefix. So we have two questions:
Do we put the module type variable in the templates?
If so, do we make this variable mandatory or do we leave the option of the file name prefix?

[stoobie]

@emmurphy1 I think that everyone that has expressed an opinion so far here agrees unanimously that the variable should be in the templates, and I think that it should be mandatory, because it's the safest way to ensure that the content type metadata gets into Pantheon 2. And that is especially true given your statement:

Currently, file names have many variations between documentation groups and not all groups have the module type at the beginning of the file name, or even at all.

As @benradey says, it's a lot easier to add a variable than it is to change a file name, and it would be nice to have one less thing to do in order to migrate content into Pantheon 2.

[pwright]

@emmurphy1 @stoobie
How about trying to express this as release note item, here's my go 😄

With this release of PV2, the primary method of setting module type becomes the _module-type attribute. CCS recommends setting the _module-type attribute to determine module type. However if _module-type is not set, PV2 uses the filename prefix.

NOTE: If _module-type is set to procedure and the filename prefix is set to con_, PV2 processes the module as a procedure, that is, the attribute takes precedence over the filename prefix. CCS recommends using a single method of defining module type to avoid these situations.

There is currently no plan to deprecate the filename prefix method of setting module type.

[pwright]

An alternative (which doesn't chime with me, but might prompt others):

With the next release of PV2, setting module type using the _module-type attribute becomes mandatory as the method of determining module type.

NOTE: If _module-type is set to procedure and the filename prefix is set to con_, PV2 processes the module as a procedure, that is, the filename prefix is ignored. It is up to the writer to avoid these situations.

[stoobie]

@pwright Good idea, but I don't read the Release Notes very often. I think this note should be in the actual text of the guide where the _module-type attribute is mentioned. I would make it more general, using your text as an example.

[emmurphy1]

Thanks @pwright and @stoobie. @rkratky what is your opinion? This is a major change to the templates so want to make sure we have considered all of the pros and cons.

[rkratky]

@emmurphy1, I don't agree with adding it to the templates. It's not related to and/or necessary for mod docs. It's required by Pv2, which is just one of the many ways to work with mod docs content sources. So, in order to keep the templates implementation-agnostic, I wouldn't want to add stuff like this. As it is now, the mod docs project is an open-to-anyone resource.

For Red Hat's purposes, we may want to keep a list of additional requirements (we already do), such as repo structures, meta files (docinfo.xml, ...), attributes, etc. But it should not "pollute" the upstream mod docs project.

[rkratky]

To amend my previous comment: If there's consensus that this is a valuable addition to the mod docs format, then I have no objections. I just want to make sure we steer clear from adding implementation-specific elements that serve no other purpose than supporting the respective implementation.

That said, let's consider @pwright's comments: there already is a mechanism for determining module type in the guidelines (file name prefixes). Therefore, I'd suggest that if this attrib. is added to the templates, then the updated wording of the guidelines should say that either one of these mechanisms can be used. Using at least one is recommended (i.e. either prefixes or the attrib.).

[Levi-Leah]

I think we should add this attribute with a note as per Robert's suggestion that stresses that the tag takes precedent over the file name. This will ensure that we accommodate the teams that do not follow the file naming guidelines and don't make them jump through the hoops. Because asking a team to add a tag to their file to make them Pv2 compatible is realistic, asking them to rename the files is not. And if we add the tag to the templates the tech writers working on the Pv2 conversion have one less thing to worry about.

[pwright]

My concern is that folks follow the filenaming convention, add the tag... then end up with contradictory filename/tag and cannot understand the results. Sure a note might help, but if the tag is primary, then perhaps the templates shouldn't follow the filenaming convention as way to alert writers "Wow, the templates don't follow the file-naming convention, I wonder why ?".
It's the doubling up that will confuse when things go wrong IMO

[emmurphy1]

@rkratky @pwright @Levi-Le thank you for this discussion. Robert, I completely agree that we should do our best to keep the templates 'clean'. I think this is a worthy exception that we should add to the templates and we should the promote it over the file name method. This will benefit doc groups that do not currently follow the recommended file naming conventions. Also, we can review the file naming recommendations in the Mod Doc Reference Guide to perhaps make them more community friendly.

[sterobin]

I've tried not to add another comment to this long convo, but just wanted to mention that whatever we decide, it will be important to ensure that the file name prefix continues to be supported as an alternative to the variable. While for some teams prescribing file names is highly impractical, for other teams introducing yet another variable for every single module can also be a lot of clutter, especially where we're implementing UI-based quick start metadata and ascii splitter metadata already. Example, on Managed Kafka, we're doing our best to minimize metadata as much as possible to reduce the overhead in the source, and using the file name alternative for module types has been very helpful. I know that other teams are in the same boat. So both options have their proper place and use case.

However, if maintaining two different options becomes unsustainable, then the variable option seems most practical and most widely adoptable at any stage of content maturity.

[emmurphy1]

Thanks to all who contributed to this discussion. At the review board meeting today, we concluded that both options to indicate module type are equally legitimate. It's a matter of preference for individual writing groups. The two options are already documented in the Modular Documentation Reference Guide.

For clarify, we opted to add a note to the templates in PR 164:

@Levi-Le, I believe the focus of your original request was to make sure that when the variable is used that it is placed above the ID so I have called that out in the note.

[emmurphy1]

The templates were updated in #164.

[emmurphy1]

@adahms please add to the decision register.

[stoobie]

@Levi-Le Taking into account the decision that was made here, please make sure that when browsing files in Pantheon 2, both the variable and the filename are considered when creating search results. I noticed previously that files that did not include the module_type attribute did not appear in search results when I sorted by file, and accordingly I created a module in Pantheon 2 help to indicate that you need to add the attribute in order to enable proper search results. This decision impacts Pantheon 2 functionality and, accordingly, Pantheon 2 end-use documentation.