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

Are modules required in all assembies #122

Closed mburke5678 closed 4 years ago

mburke5678 commented 4 years ago

The Modular Documentation Reference Guide seems to suggest that assemblies must have a module: The required parts of an assembly are the introduction and modules. (emphasis added) [1] However, there seem to be times where a module is not necessary for understanding the content. For example, I have this topic that doesn't seem that it would help to have a module. All the information can be contained in the assembly; a module seems superfluous. [2]

[1] https://redhat-documentation.github.io/modular-docs/#assembly-guidelines [2] https://github.com/openshift/openshift-docs/pull/23502/files#diff-cbc6ad36f690e81275dd6a5cc70ebba7

VladimirSlavik commented 4 years ago

No longer a writer, but: That looks like a concept or reference module to me, not an assembly. I always thought an assembly has a minimal intro text, and the bulk of content is in modules.

emmurphy1 commented 4 years ago

@mburke5678 Yes, an assembly must include at least one module. The purpose of an assembly is to group related modules together with include statements. It was never the intent that an assembly be published without a module even though this is possible.

emmurphy1 commented 4 years ago

This decision is recorded in the Flexible Customer Content Decision Register, decision D12.