This is the mail archive of the mailing list for the DocBook project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [docbook] Ruminations on the future of DocBook

My 2 cents:

I think that one of the major problems is that many of us have never been trained to properly use the DocBook. We figure it out as we go along and misuse it at the same time. I know I have. Information is provided in the DocBook reference but sometimes it requires one to understand the jargon to an extent a newbie just doesn't. This text could be reworked to accommodate more self taught individuals and our not understanding the jargon yet.

Another problem is that some people just don't understand proper document structure at all. I work as a tech writer and know many people who cannot properly tag a document in FrameMaker or (gag) Word. These people completely sabotage all attempts at moving to XML. I won't even go into the fact that most of these people have no understanding of the technology they write about because that's too far off topic.

I agree that the number of tags could be reduced if done properly. Maybe this makes more sense if we rely on attributes more for providing information about the intended use. For example why have <note>, <important>, <caution>, <warning>, <tip>? Maybe a single tag could have been used with the differences being made with role:

<attention role=caution> <para>Don't touch that!</para></attention>.

The same could have been done with sections: <section>This is just a section</section> or
<section role=numbered>This section gets a number.</section>

I know that this is water under the bridge (especially considering the need to support existing documents), and my not simplify things, but with my limited experience with DTDs it seems that it may provide some way of simplifying the structure while allowing the complexity to be handled through the use of attributes.

Another problem is how we look at the world. For example there is the discussion about a <task> element. I usually use the word "process" (high level) rather than "task" in contradistinction to "procedure" (low level). This may lead to excessive elements or not realizing one's needs are already met. This may be a poor example because there is no <process> or <task> element at the moment but there may be very closely related elements that could have used the same term. This happens a lot in programming languages such as "method" versus "function". Perhaps a careful generalization could be done to accommodate similar functionality but different terms (jargon).

I may be off-base but those are a few of my thoughts, for whatever they're worth.

Jeff Biss

Jeff Biss

Norman Walsh wrote:

Hash: SHA1

After the last DocBook TC meeting, I found that I was feeling rather
depressed. Well, maybe depressed is too strong a word. But it wasn't a
happy feeling.

It's hard to articulate exactly why. I think it's because DocBook is
showing its age. There comes a point in the life cycle of any system
when adding one more patch is the wrong solution to every problem.
Eventually, it's time to rethink, refactor, and rewrite.

For DocBook, I think that time has come.

I've written a couple of essays[1][2] about this and published them

More thinking is definitely in order. By more minds than mine, which
is why I'm publishing these essays now.

I want to emphasize that this is very much my opinion and that I'm not
speaking for the TC (or my employer, or anyone else). And I reserve
the right to be completely wrong. :-)

                                       Be seeing you,


- -- Norman Walsh <> | Things work out best for those who | make the best of the way things
Chair, DocBook Technical Committee | work out.
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.7 <>


To unsubscribe, e-mail:
For additional commands, e-mail:

--------------------------------------------------------------------- To unsubscribe, e-mail: For additional commands, e-mail:

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]