Updates regarding ID's for headings

[ncbaratta]

I'd like to propose the following additions to the guidelines to accommodate accurate and consistent URLs on the new docs site:

• every heading should have an ID
• no ID should have the con_, ref_, assembly_, or proc_ prefix
• IDs should never be changed (once published), even if the heading changes or the ID has a typo
• IDs should not include extraneous words because they will appear in the URL. ex. upgrading_red_hat_enterprise_linux_to_version_10 could be upgrade_rhel_to_v10
  • product names in IDs can be shorted to remove "red hat" because that is in the URL already, and can use approved short forms because this is a space-confined location

[mjahoda]

Hi Nicole,

I will share my opinion:

* every heading should have an ID

You probably meant every non-discrete heading. However, I can imagine that even this might be unnecessary in many cases and considered as a rule without any practical benefit. I may be missing some good reason though.

* no ID should have the con_, ref_, assembly_, or proc_ prefix

100% agree.

* IDs should never be changed (once published), even if the heading changes or the ID has a typo

This is IMHO a convention that should be project-specific and more fine-grained. In the case of modules, you can preserve the existing links by using the multiple IDs feature:
https://gitlab.cee.redhat.com/red-hat-enterprise-linux-documentation/rhel-8-docs/-/wikis/Preserving-module-IDs-and-link-anchors-when-renaming-a-module
In some other cases, you can realize that it might be still better to fix some horrible typo in a URL, because there'are probably not many existing backlinks (you cannot influence).

* IDs should not include extraneous words because they will appear in the URL.  ex. upgrading_red_hat_enterprise_linux_to_version_10 could be upgrade_rhel_to_v10

Mostly agree, but this does not seem to be a mod-docs-specific convention (RH SSG?).

  * product names in IDs can be shorted to remove "red hat" because that is in the URL already, and can use approved short forms because this is a space-confined location

As in the previous point.

Thank you for bringing this up. In general, I think we should add at least some guidance you're proposing.

[ncbaratta]

You probably meant every non-discrete heading. However, I can imagine that event this might be unnecessary in many cases and considered as a rule without any practical benefit. I may be missing some good reason though.

Yes I did!

[emmurphy1]

@ncbaratta we discussed this at the Modular Documentation Steering Committee and in general are in agreement to add these guidelines to the reference guide. However, can you explain more about adding IDs to each heading? Do you mean each major (==, ===. etc) non-discrete heading? And what is the reason for this? Thanks.

[ncbaratta]

I'll leave this to the current metadata committee to answer. Email them at CCS Metadata Governance Council ccs-metadata@redhat.com