On topics

[Norman Walsh <ndw@nwalsh.com>]

N.B. The following represents my personal opinion only.

In preparation for today's DocBook TC meeting, Bob put together a list
of relevant threads[1] (thanks, Bob!) and I've gone back over those
threads, the proposals, and my own notes. In the intervening months,
I've also had more time to think about authoring methodologies.

"Topics" in one form or another have been a perpetual topic. Old
timers will tell you we used to talk about it in the Davenport days
when some really bright guys from Novell had all sorts of ideas about
authoring help systems in DocBook. That must have been circa 1995.

As a general rule, if someone asks for markup "X" and DocBook already
has markup "Y" that can be used for the same purpose without too much
tag abuse, we tend to encourage the requestor to use "Y" instead.

The proposals for topics, as far as markup goes, all seem to be
isomorphic, or nearly isomorphic, to article or section. And lots of
folks have demonstrated that it is possible to write modular,
topic-based documentation in DocBook using those elements.

There are some wrinkles in the actual RFE[2] that have to do with
modifying content models and effective searching with particular
tools. I'm not quite sure how to address those, and as much as I'd
like to help SolBook remain a strict DocBook subset, it's not clear to
me that they those are processing expectations so broadly understood
and common that they warrant a change to the DocBook standard.

The other motivating factor, I think, is the popularity of DITA.

Adding a "topic" element to keep up with DITA, as noted above, is
technically unnecessary. This seems particularly the case because when
I mention the other DITA features that we could add, like scoped IDs
and conref, smart DITA users tell me "oh, no, [insert some reason
about utility or complexity] don't do that."

If it's technically unnecessary then we must be considering doing it
for social, political, or other non-technical grounds.

On those grounds, I'd rather not.

I think the topic-oriented methodology tends to produce poorer quality
documentation anyway[3] so I'm not sure how to sell adding it to
DocBook as a feature.

At the end of the day, I think there's a chorus of voices in the
DocBook community suggesting that adding topic to DocBook V5.0 would
be a mistake. I'm inclined to add my voice to that chorus.

Now the question of how to build better modular documentation with
DocBook, implementing some sort of variation on the "map" theme, does
seem like it has some support and does seem like a good idea.

I think it'd be great if someone built two or three or ten of those so
we could see which ones actually work best for DocBook. Then maybe we
could think about standardizing it.

My two cents.

                                        Be seeing you,
                                          norm

[1] http://lists.oasis-open.org/archives/docbook-tc/200702/msg00002.html
[2] https://sourceforge.net/tracker/index.php?func=detail&aid=1097183&group_id=21935&atid=384107
[3] http://norman.walsh.name/2007/02/05/painting


-- 
Norman Walsh <ndw@nwalsh.com>      | Everything should be made as
http://www.oasis-open.org/docbook/ | simple as possible, but no simpler.
Chair, DocBook Technical Committee |

PGP signature