Fix metadata in templates from content_type to module_type about modular-docs

[heathjoy]

I am in support of Emily's and Nicole's argument for reserving content_type to align with our standardized content types definitions. This also keeps us in alignment with how content types are referred to across the organization, not just in CCS. Our new tooling and docs experience enables us produce and track our content (via content types) across the entire user journey which spans multiple site systems.

[emilyoneill]

The Metadata Governance Committee requests that we change this from _content-type to _module-type which is more accurate and will allow for us to use "content-type" for the actual content types to be defined.

Just wanted to add my support for this change for all the reasons @ncbaratta has mentioned above. It is vital that our new experience is supported by metadata for tracking and customisation. One facet of this is tracking our defined content types as we evolve our docs experience from 'books on the portal' to a more modern digital content experience.

[ncbaratta]

@ncbaratta will the new tool chain support or need to support assembly and snippit files?

It will, but I don't see a problem calling it module type even if it's an assembly or snippet - they're all modules. I actually don't care if it's called '_ice_cream' as long as it's not '_content_type' which is a reserved term for the content type research that's being done.

If is possible that some groups are using this attributes so how should we communicate this change to them?

When they moved to the new tools we'd have something in place to fix this so that no effort would be needed by the folks using it (which if I understand right isn't many)

[ncbaratta]

Yes, it will be required, both content_type and module_type ;) and many other terms eventually, but the MVP for the docs tooling has these two (which are not the same thing) as required.

[emmurphy1]

@bergerhoffer suggests :_mod-docs-content-type:.

@ncbaratta and @heathjoy any objections?

[mjahoda]

Does anyone know why we have the leading underscore?

Because of parsing (this distinguishes metadata from other AsciiDoc attributes).

[emmurphy1]

@ncbaratta I did some digging about this history of this variable. It started out as module_type and was required by PV2:
#151
In August, 2022, it was changed to _content-type to include assembly and snippet files:
https://github.com/redhat-documentation/modular-docs/pull/191/files

@abhatt-rh because you raised this issue to change to _content-type, do you see any blocker to changing it back to module-type?

@ncbaratta will the new tool chain support or need to support assembly and snippit files?

If is possible that some groups are using this attributes so how should we communicate this change to them?

[abhatt-rh]

@ncbaratta I did some digging about this history of this variable. It started out as module_type and was required by PV2: #151 In August, 2022, it was changed to _content-type to include assembly and snippet files: https://github.com/redhat-documentation/modular-docs/pull/191/files

@abhatt-rh because you raised this issue to change to _content-type, do you see any blocker to changing it back to module-type?

@ncbaratta will the new tool chain support or need to support assembly and snippit files?

If is possible that some groups are using this attributes so how should we communicate this change to them?

Hi @ncbaratta, thank you for submitting this issue. I had a few of ques related to this:
Is the Metadata Governance Committee proposing this change based on the our new tooling requirements? Are they working in tandem with the tooling committee? Just wanted to understand if this is subjected to further change when move to the new tooling.

Hi @emmurphy1, thank you for tagging me here.
I submitted the issue and PR for getting this updated to _content-type based on Jupiter recommendations. Also, our mod-docs templates were already using this metadata, but the guidance was not in sync with the templates.

Further, on the ques of whether I see a blocker, I suppose this needs to be discussed more widely. As Emily pointed out that there are teams that use this metadata in their projects. I know that the OpenShift docs team underwent an exercise to add and update this metadata a few releases ago. Also, OpenShift docs team uses it for assemblies and snippets, where using _module-type might be inaccurate or confusing too.

As small as the effort might be to update this metadata (possibly a search and replace activity), in the spirit of being open and transparent, I feel that it might be best to socialize this change first before we implemented it here so that teams using it have enough time to accommodate for it.

cc: @kalexand-rh and @bergerhoffer for awareness and for any additional comments on OpenShift docs.

[ncbaratta]

Hi @ncbaratta, thank you for submitting this issue. I had a few of ques related to this: Is the Metadata Governance Committee proposing this change based on the our new tooling requirements? Are they working in tandem with the tooling committee? Just wanted to understand if this is subjected to further change when move to the new tooling.

The committee is tasked with making recommendations to the tooling team. As Data Program Manager I'm tasked with outlining the data requirements for the new tooling. We're just looking to have "content_type" be used for content types and not file types/module types

As small as the effort might be to update this metadata (possibly a search and replace activity), in the spirit of being open and transparent, I feel that it might be best to socialize this change first before we implemented it here so that teams using it have enough time to accommodate for it.

Agreed, spread the word, do this in the open, and as I said above no work will be required by those using this now, we will have a script make the change for them when they move to the new tooling.

[abhatt-rh]

Hi @ncbaratta, thank you for submitting this issue. I had a few of ques related to this: Is the Metadata Governance Committee proposing this change based on the our new tooling requirements? Are they working in tandem with the tooling committee? Just wanted to understand if this is subjected to further change when move to the new tooling.

The committee is tasked with making recommendations to the tooling team. As Data Program Manager I'm tasked with outlining the data requirements for the new tooling. We're just looking to have "content_type" be used for content types and not file types/module types

As small as the effort might be to update this metadata (possibly a search and replace activity), in the spirit of being open and transparent, I feel that it might be best to socialize this change first before we implemented it here so that teams using it have enough time to accommodate for it.

Agreed, spread the word, do this in the open, and as I said above no work will be required by those using this now, we will have a script make the change for them when they move to the new tooling.

Thank you for explaining it, @ncbaratta! Sounds good.

[emmurphy1]

@ncbaratta because you are possibly privy to the requirements, limitations, possibilities, etc... of the new tool chain, can you tell us if we will even need the :_content-type: variable in the future? And if we change it back to :_module-type:, or change it to :_ice-cream: or whatever, do we need to ask writers that are currently using :_content-type: to change that variable now to continue publishing on PV2 or can they continue to use:_content-type: until we migrate to the new tool chain? Also, I don't know if PV2 is looking for :_content-type: now instead of :_module-type:.

Just for the record, I am not in favor of using :_module-type: as a variable name for non-module content, so of the two, i vote for ice-cream :-)

[ncbaratta]

@ncbaratta because you are possibly privy to the requirements, limitations, possibilities, etc... of the new tool chain, can you tell us if we will even need the :_content-type: variable in the future? And if we change it back to :_module-type:, or change it to :_ice-cream: or whatever, do we need to ask writers that are currently using :_content-type: to change that variable now to continue publishing on PV2 or can they continue to use:_content-type: until we migrate to the new tool chain? Also, I don't know if PV2 is looking for :_content-type: now instead of :_module-type:.

"need" - no ;) "want" - yes.

So, this has nothing to do with a system requirement and everything to do with tracking types of modules and content we have in our system. Tracking traffic to concepts over procedures and quickstart over release notes (just making up comparisons). Metadata will allow us to track whatever we want and will allow us to allow customers to drill down their searches in any way they want. Will they want to drill down to find only procedures? Maybe? We don't know that part yet, but we do know that we want a content inventory and in order to get that we need metadata tags including module_type and content_type and many many others.

Just for the record, I am not in favor of using :_module-type: as a variable name for non-module content, so of the two, i vote for ice-cream :-)

How is a snippet not a module? The vocabulary for defining pieces of content will be called 'Module' so it matches the database where our terms are stored.

[emmurphy1]

Thanks for that context, @ncbaratta . And great question about snipppets. A module as defined within our modular documentation module must have an anchor ID in the specified format and an H1 title. Other variations in structure define what type of a module a module is. And within that definition I won't object to including assemblies in the :_module-type: variable. However, a snippet must NOT have an anchor ID or an H1 title. My main objection to including snippets in the :_module-type: variable is that writers are already sometimes confused about the fundamental differences between modules and snippets. Make sense?

[emmurphy1]

@ncbaratta at the moment the :_content-type: variable is optional and AFAIK only a few writing groups use it. Will it be mandatory in the future? Otherwise, how will it be useful for tracking data?

[ncbaratta]

We have votes for simply "type" or "file_type" (to define the module type - since we can't use content-type) in our metadata governance committee meeting.

[ncbaratta]

@emmurphy1 Just wanted to check in here to see if you have a recommendation on a term we can use instead of content-type? Or do you like any of the suggestions above?

[emmurphy1]

During the CCS Data Office Hours meeting, we came up with these suggestions:
:_info-type:
:_def-type:
:_definition-type:
I posted a question on the forum-ccs-mod-docs Slack channel.

Does anyone know why we have the leading underscore?

[ncbaratta]

Vote from data office hours

[ncbaratta]

Nope, no objections from me.

[heathjoy]

No objection from me

[emmurphy1]

I create the following pull request:
https://github.com/redhat-documentation/modular-docs/pull/209/files

I simply changed the variable name without explanation. After we merge this change, we will send out a detailed email explaining the reason for the change and options for updating repos that use this variable.

[rolfedh]

Hi @emmurphy1
I confirmed with @ncbaratta that #209 fixes this issue.
Please, would you close it? Thanks.

[mjahoda]

Resolved by #209