Add an assembly attribute option

[kalexand-rh]

An emerging requirement for the Ganymede build system is to explicitly identify each assembly as an assembly. The current guidelines provide a suggested assembly file name prefix (assembly_) but, unlike the module types, does not provide a corresponding attribute.

@xdavidson suggested using :_doc-type: ASSEMBLY as the assembly attribute.

[vikram-redhat]

I think we should wait till we have a full list of requirements coming out of Ganymede that are different from PV2 requirements before proceeding with this change and then consolidate those changes.

I believe in one of the initial calls any PV2 compliant repo would work as is in Jupiter/Ganymede, so we probably need to confirm that there are going to be changes, and communicate to CCS.

[thatdocslady]

I agree with @vikram-redhat. Also, the new attribute in the PR makes the attribute names inconsistent (module_type vs doc_type, in my mind they should all be doc_type), which leads me to think that this might be a bigger conversation to have and then apply the changes a more standardized approach.

[mjahoda]

I am afraid that we are back to the already mentioned problem - creating standards for tooling purposes. It should work the other way round.

[xdavidson]

Here is some background information on why requesting the new attribute, "_doc-type".

• PV2 processes pantheon2.yml and uploads one file one at a time to the build process over the network to convert the asciidoc to html. At upload time, PV2 knows which file is assembly or module as this information is user-defined in the yaml.
• Ganymede processes the yaml file and provides the top level directory with files specified in the yaml file to the build service. That directory is stored on a shared storage for the build service. At build time, the build service converts the repository given in one shot/one api call using Asciidoctor API convertDirectory.

There is an existing attribute called "_module-type". It has three possible values: CONCEPT, PROCEDURE, REFERENCE

e.g. [llu@llu openshift-docs (rhacs-docs)]$ head -5 modules/enable-admission-controller-enforcement-55.adoc // Module included in the following assemblies: // // * operating/use-admission-controller-enforcement.adoc :module-type: PROCEDURE [id="enable-admission-controller-enforcement-55{context}"]

"assembly" is not a module, It does not make sense to add a new value to the above attribute. Ideally, we would like a new attribute called something like "_doc-type" that indicates if an adoc is an assembly or not.

[sterobin]

So @xdavidson @vikram-redhat @mjahoda @thatdocslady and all, after further discussion and assessment with @kalexand-rh and others in the working group, the change we're proposing instead is to simply change _module-type to _content-type, which would then broaden the scope of the tag to include not only the type of module, but also assemblies, snippets, and even multimedia perhaps down the road.

@mjahoda I wouldn't consider this a change to comply with Jupiter/Ganymede, nor with Pv2, but a genuine enhancement to our content tagging that previously was imo just too narrow (only about modules). This change makes the tag more future-friendly, as Laura Bailey put it. The fact that it would help tooling as well is an added bonus, in my view.

So this would be the new attribute and values:

:_content-type: CONCEPT | REFERENCE | PROCEDURE | ASSEMBLY | SNIPPET | MULTIMEDIA | etc

[kalexand-rh]

I've updated the PR to use the :_content-type: variables in both the guidelines and the templates.

[bhardesty]

In Pantheon 2, we explicitly identify assemblies using the assemblies section in pantheon2.yml. Will this not work for Ganymede? From what I can glean from the Ganymede build file and left nav menu requirements, this assemblies section is still present in the recommended pantheon2.yml file. If this is accurate, then why would we need to explicitly set the content-type in every file when it's already set in pantheon2.yml?

[kalexand-rh]

In Pantheon 2, we explicitly identify assemblies using the assemblies section in pantheon2.yml. Will this not work for Ganymede? From what I can glean from the Ganymede build file and left nav menu requirements, this assemblies section is still present in the recommended pantheon2.yml file. If this is accurate, then why would we need to explicitly set the content-type in every file when it's already set in pantheon2.yml?

@xdavidson, can you explain to @bhardesty how the assembly marking factors into the directory crawling?

[sterobin]

In mod doc review board meeting Dec 8, 2021, decided to freeze this issue and it's PR until the dust settles with Jupiter post-Summit to ensure that the requirements don't again change, and also to see at that point if we can get a concrete answer on how the distinction of content and even module type has actual customer value beyond just a new tooling requirement. To be discussed post-Summit.