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

Add guidance about subheadings in cons and refs. #140

Closed sterobin closed 3 years ago

sterobin commented 3 years ago

Addresses issue #137

sterobin commented 3 years ago

@oraNod Thanks for the feedback. I guess your points are exactly what this PR is intentionally trying to make less prescriptive. What I mean is, there is a tradition in CCS that cons and refs really shouldn't have subheadings and that writers should favor splitting modules into standalone units, just as you're saying. As a result, many writers are creating artificial modules that really aren't standalone just for the sake of avoiding subheadings and to comply with the preference to break modules apart.

Regarding the discrete/float heading, your preference to retain that tag is again what this PR is attempting to loosen. Meaning, writers are likewise under the impression that if you do use subheadings in cons and refs, they should be discrete. The problem there is that there are many cases where content should not be discrete so that it appears in the TOC, but where that subheading isn't a candidate for it's own module. A recurring example is API reference content, especially endpoints, which in some cases make more sense to be collected as part of the same reference module, but would benefit from being listed in the TOC (non-discrete).

This is all highly subjective and relies on the writers' judgement, so I suppose my purpose here is to open things up a bit more to writers' needs and not be quite so prescriptive. But if you and others feel that your perspective is still the commonly shared feeling of what we ought to be conveying, then basically I can just disregard this PR and let that tradition continue on as it is. We'll see what others think and go from there. I won't be offended if I'm alone in this.

oraNod commented 3 years ago

Thanks for explaining the purpose a bit more @sterobin Maybe I'm going in the total opposite direction but I still think the wording makes things a little open to interpretation.

theashiot commented 3 years ago

I guess the modules in this PR are the perfect example of why it's good to have subheadings. The modules "Concept Module Guidelines" and "Reference Module Guidelines" without the subheadings would become difficult to read. Splitting the modules into, for example, "Reference Introduction", "Reference Body" would not make sense.

The changes look good to me!

sterobin commented 3 years ago

@theashiot Exactly! +1 Thanks for the review.

rkratky commented 3 years ago

@sterobin, please, see my comment in the orig. issue: https://github.com/redhat-documentation/modular-docs/issues/137