New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Fix metadata in templates from content_type to module_type #203
Comments
@ncbaratta I did some digging about this history of this variable. It started out as module_type and was required by PV2: @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: Hi @emmurphy1, thank you for tagging me here. 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 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. |
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.
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) |
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
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. |
@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 :-) |
"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.
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. |
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? |
@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? |
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. |
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. |
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. |
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. |
@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? |
During the CCS Data Office Hours meeting, we came up with these suggestions: Does anyone know why we have the leading underscore? |
@bergerhoffer suggests :_mod-docs-content-type:. @ncbaratta and @heathjoy any objections? |
Nope, no objections from me. |
No objection from me |
Because of parsing (this distinguishes metadata from other AsciiDoc attributes). |
I create the following pull request: 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. |
Hi @emmurphy1 |
Resolved by #209 |
The Metadata Governance Committee is coming up with terms for our taxonomy and one of them is content type, another is module type. Right now our templates have lines like this in them:
//// Indicate the module type in one of the following ways: Add the prefix con- or con_ to the file name. Add the following attribute before the module ID: :_content-type: CONCEPT ////
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.The text was updated successfully, but these errors were encountered: