Re: [docbook] Ruminations on the future of DocBook

[Jeff Biss <jeff at marco-inc dot com>]

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:

> -----BEGIN PGP SIGNED MESSAGE-----
> 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
> on http://norman.walsh.name/
>
> 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,
>                                          norm
>
> [1] http://norman.walsh.name/2003/05/21/docbook
> [2] http://norman.walsh.name/2003/05/29/moredocbook
>
> - -- 
> Norman Walsh <ndw@nwalsh.com>      | Things work out best for those who
> http://www.oasis-open.org/docbook/ | make the best of the way things
> Chair, DocBook Technical Committee | work out.
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.0.6 (GNU/Linux)
> Comment: Processed by Mailcrypt 3.5.7 <http://mailcrypt.sourceforge.net/>
>
> iD8DBQE+1lgzOyltUcwYWjsRAs2kAJ9c0q08PBWl7OUvXmczqVrmPUW7/gCcCTKj
> 66nldCo6Oakw2fRlp+UMmlo=
> =LE5w
> -----END PGP SIGNATURE-----
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-help@lists.oasis-open.org



---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-help@lists.oasis-open.org