Eliminate 'hanging paragraphs'

[dwsinger]

we have a number of sections that have both text (before the first sub-section) and sub-sections. I think it's better practice to have one or the other, but not both. Is, for example, a reference to 2.1.3 to the paragraphs before 2.1.3.1 or to the whole sub-section?

[dwsinger]

Section 4 is particularly amusing. It has hanging text, but only one sub-section (4.1, no 4.2) which in turn has hanging text but again only one subsection (4.1.1).

which suggests we should also simplify by looking for sections that have only one sub-section, and either provide a sub-section heading for the hanging text (if any) or remove the only sub-section heading.

[fantasai]

Aww. I like hanging paragraphs. Tab and I use them all the time to give introductory material applicable to all the subsections. I get the concern about cross-references, though; is it a real problem?

[frivoal]

4
  brief intro
  4.1
    some stuff
  4.2
    some more stuff

isn't necessarily bad, though it makes references to "4" a little ambiguous. On the other hand, this doesn't make a whole lot of sense:

4
  half the section
  4.1
    more content
    4.1.1
      one more thing

[palemieux]

I get the concern about cross-references, though; is it a real problem?

FWIW, I have been in several situation where the inability to precisely reference the hanging paragraph caused confusion: when referencing the hanging paragraph from another document or in discussions.

Example: see Clause 3 for a description of the widget where clause 3 is 10 pages and the description is in the hanging paragraph immediately following the Clause 3 header.

[dwsinger]

I agree, sentences of the form "this section introduces wombats and describes the requirements for international transactions involving them" is pretty harmless. The trouble is, once you have hanging paragraphs, people are tempted to say "and they MUST be treated the same as, or better than, aardvarks" and of a sudden "the requirements of clause 3" is ambiguous: the hanging paragraph only, or 3 and 3.1, 3.2 etc.?

I won't be pedantic about it, but we should skim and make sure that if we have them, they are of the harmless type.

and yes, the structure of section 4 is, well, peculiar.

[dwsinger]

propose to close, we cleaned 4 this year and the rest seem fairly harmless

[frivoal]

We actually did more than just section 4, the reorg fixed a few more of that type of problem. Should have closed this when landing the reorg, so doing it now.