search

redhat-documentation / modular-docs

Modular Documentation Project provides guidelines and examples for writing technical documentation using a modular framework.
Creative Commons Attribution Share Alike 4.0 International
82 stars 68 forks source link

Optional standard for file name prefixes #109

Closed fbolton closed 3 years ago

fbolton commented 4 years ago

There has already been a comprehensive discussion about the pros and cons of using file name prefixes to indicate the module type (#25). But I would like to make a slightly different proposal. I would like to suggest the following guidance for using prefixes.

A modular documentation project could:

  • Not use file name prefixes at all OR
  • If the project uses prefixes, it SHOULD use a standard set of prefixes.

The background to this is that we currently have a situation where some projects do not use file name prefixes (which is fine and is what was agreed in #25) and some projects do use prefixes (which I understand is also an acceptable practice, according to #25). But for the projects that do use prefixes, I recently discovered that we are using different prefixes. For example, the Fuse documentation project is currently using the prefixes p_, c_, and r_, whereas OpenShift is using proc_, con_, and ref_. For those projects that are using prefixes, it would be convenient (and less confusing) to agree on a standard set of prefixes, particularly when sharing content. This would not in any way affect those projects that do not use prefixes, who would be free to continue not using prefixes.

adahms commented 4 years ago

Thanks for raising this issue, @fbolton!

I completely agree - having a standard approach is good, and helps teams update and change them in the future should there be any need.

There have been a few meetings about tooling progress in the last few days as well, and there might be some details coming out of these talks that could help here, too. I'll check and see how things are and get back to the thread here.

emmurphy1 commented 3 years ago

This issue was resolved in https://github.com/redhat-documentation/modular-docs/pull/121 and the changes incorporated in the Reference Manual.