June 10, 2011


This is sort of nerdy and writerly, but this is supposedly a blog about technical writing--if there isn't a place for nerdy and writerly....
A few weeks ago there was an e-mail thread on the DocBook mailing list about the best practice for using the sect1, sect2, ..., sect5 tags. Someone suggested that nobody should use those elements and just use the infinitely nesting section element. They went as far as suggesting that the offending sectN elements be removed in the next rev of DocBook.
I agree with this sentiment. While I can see the basic desire to know if I'm writing a section or a sub-section, I rarely find it to be a need. My basic organizational style doesn't involve more than three levels of sections. It also, generally, ends up with a structure such that higher level sections are just containers for lower level sections. Therefore, it is rare that I ever find myself caring or wondering what section level I'm at. It is usually three or less and if I'm filling it with a lot of content it is the deepest level I'm going to hit for the topic at hand.
Even when I do find myself wishing the schema would tell me how deep I've gone or enforcing depth limits, the added flexibility of nested sections overrides the wish. The sectN elements make reusability tough. A sect3 must always be placed inside a sect2, but a section can be a sect3 or a sect2. I have seen several cases where a section was a top level in one guide and a nested section in another.
There were several people on the mailing list who did not agree with the idea of doing away with the sectN elements. One claimed that it was imperative to enforce section levels. Another just said that you can feel free to remove any elements you want, but it wouldn't be DocBook anymore. I can see that for some writers, or writing groups, it might be important to enforce section levels. However, there are ways of enforcing style guidelines than encoding them into a schema. We do it by being disciplined and occasional peer editing.
I can also see the value of keeping the sectN elements in place for legacy documents. This, in my mind, is the best reason for keeping them. There is a lot of content out there that is using DocBook and likely a lot that use the sectN elements. It doesn't hurt too much to keep the elements in place while encouraging people to use the section element instead.

No comments:

Post a Comment