Add line about leveloffset.

[sterobin]

Addresses #112 . Apparently there has historically been a misunderstanding among CCS teammates that leveloffset is prohibited in mod docs. @pwright as part of his submitted issue suggested the simple added text shown in this PR to clarify that. The issue is already addressed in the assembly template itself here: https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc, so this small text addition should remove all doubt and close the loop.

I realize that we're trying to avoid getting into ascii syntax suggestions etc. as part of mod docs, but Paul made a strong case that there is confusion out there. So if this clarifies that, then seems to deserve the mention.

[rkratky]

@emmurphy1 @pwright Thanks for the addition. I'd say we can be even more authoritative in this case. All modules should use level 1 main headings to enable seamless reuse. So, we probably should mandate the use of leveloffset.

On a related note, I don't think I understand the reasoning behind the leveloffset values suggested in the assembly template (2 and +2). The explanation talks about nesting modules, which I thought is discouraged. Why put it in a template then?

[rolfedh]

The explanation talks about nesting modules,

By nesting, do you mean something like this?

include:<module-file.adoc>[leveloffset=+1]
include:<module-file.adoc>[leveloffset=+2]
include:<module-file.adoc>[leveloffset=+1]

I've seen folks use nesting as a convenience, because they don't want to fix the H2 title in the module, not because it's necessary. I think our guidelines should make a preference for [leveloffset=+1] and H1 titles clear.

[rkratky]

No, I understand nesting as

module
     |--> module

I've seen folks use nesting as a convenience, because they don't want to fix the H2 title in the module

Well, a module with H2 in the beginning is pretty much useless from mod docs perspective :(

I think our guidelines should make a preference for [leveloffset=+1] and H1 titles clear.

+1

[pwright]

@rolfedh there's already a note: You can use subheadings in concept or reference modules, but not in procedure modules.

Does that address your issue? My understanding is that, assuming you've done things correctly, there is not a preference for [leveloffset=+1] - that's what motivated me to create the issue, I was under the impression there was that preference.

[rkratky]

You can use subheadings in concept or reference modules, but not in procedure modules.

This sentence is weird. Every module, regardless of its type, should start with H1. And every module, regardless of its type, can use subheadings further down. I don't understand where the quoted guidance comes from, and what it is supposed to address.

there is not a preference for [leveloffset=+1]

I agree there should be preference to use this. That said, it's up to the writer how they structure their assemblies (incl. what level of offset they use). What's not up to the writer is how they form their modules because using anything other than H1 in the beginning of their modules makes the modules not reusable, which I consider wrong.

[pwright]

So, there might be a separate issue to explicitly state that every module starts with a H1 ?

@rkratky Are you saying that [leveloffset=+1] is your preference? should writers be guided to create sub-assemblies and avoid using [leveloffset=+2] ? ( asking because I think you missed the 'not' is my sentence that you quoted above)

[rolfedh]

I've removed this outdated comment.

[rolfedh]

Thanks for the healthy discussion, folks. I need to step away from this conversation to focus on producing content for an upcoming release two weeks away. My suggestions are just that.

[rolfedh]

I think Stetson's current revision encompasses all our concerns.

[rolfedh]

/lgtm

[rkratky]

@pwright

Are you saying that [leveloffset=+1] is your preference?

Yes. In my view, this should be the default. I.e. all modules using H1 in the beginning, and assemblies including such modules using leveloffset +1.

should writers be guided to create sub-assemblies

No.

and avoid using [leveloffset=+2]

Yes.

I think you missed the 'not' is my sentence that you quoted above

You mean in not in procedure modules? If that's what you mean, then no -- I don't see a reason to not use subheadings (provided the module starts with H1).

[pwright]

@rkratky I was confused by:

[rkratky]

@pwright, my bad. What I meant was that I was in agreement with the assertion that the lack of preference for leveloffset=+1 was a mistake/oversight. I.e. it was my "+1" to adding the leveloffset recommendation.

[sterobin]

@pwright @rkratky So are we good here? Been quite a loop and if we're now good I'd like to resolve some of these threads and then petition the rest of the approvals. Let me know. Thanks.

[emmurphy1]

Thanks @sterobin . The changes LGTM. @rkratky, @fbolton, @yzimmerm I am going to merge these changes on Thursday if we don't hear from you.