6:30 p.m.
Paul W. Frields wrote:
On Tue, 2005-08-23 at 18:48 -0500, Thomas Jones wrote:
>-----BEGIN PGP SIGNED MESSAGE-----
>Hash: SHA1
>
>On Tuesday 23 August 2005 17:09, Tommy Reynolds wrote:
>
>>Uttered Thomas Jones <admin(a)buddhalinux.com>, spake thus:
>>
>>>I have quickly built up a DTD Driver for the Docbook 4.2 release. This
>>>driver contains declarations for Fedora Core specific documentation.
>>
>>I am not in favor of this subsetting (even if it's a proper subset)
>>approach. What we have is already rigorously documented in several
>>books at Borders, Barnes & Noble, Books-A-Million, Amazon, et. al.,
>>hope I didn't leave out your favorite; if I'd remembered it I would
>>have plugged it.
>>
>
>Very good point. That definitely would be a disadvantage.
>You got my favorite. ;)
>
>
>>An "approved subset" would be yet another learning level for newbies.
>>I'd much rather see our current Documentation Guide fully-fleshed out
>>with recommended (or at least tested) examples for the
>>monkey-see-monkey-document crowd. No slur intended, but it's really
>>much easier to bang out a DocBook document with minimal learning
>>curve by just looking at an example of what you want to do; no
>>"internalized learning" required.
>>
>
>Actually, being a subset and not a superset; there is less that a end-user
>would need to learn.
I'd have to agree with Thomas and say that fewer elements simplifies the
learning curve, rather than complicating it.
For example, if a new author has a setup whereby the menu of valid tags
at cursor point shows up in her editor, she's less likely to feel
overwhelmed by the sheer number of tags from which to choose. Here's a
visual example of what I'm talking about:
http://linux.duke.edu/~mark/psgmlx/doc/blue-screenshot.html
In my experience, writers do feel intimidated by the sheer size of
DocBook (~300 elements), some choose Simplified DocBook (~100 elements)
for this very reason.
IMO, it'd be easier for an author to have a smaller number of tags
available, rather than having to look up in the docs guide which tags
are recommended. Simply eliminate those that aren't used.
FWIW, subsetting DocBook is a very common ocurrence, and for good
reason: most projects simply don't need all those elements. Also,
maintaining a subsetted DocBook dtd adds no effort to the project - it's
usually trivial to migrate the subsetted dtd to a newer version.
OTOH, extra effort would be required in that someone would need to
package the subsetted dtd. But that's about all. I honestly (I'm being
sincere here) don't understand the objections to reducing the number of
tags the authors would have to deal with. But, like Thomas, I'm looking
at this from a slightly different perspective.
>
>Take for instance the following elements:
>sidebar
>synopsis
>bridgehead
>dedication
>sect[1-5]
>
>Are any of these, needed? I hadn't realized it but somewhere in the wiki ----
>I don't remember where --- it is stated not to utilize the sect elements. It
>just so happens that as a habit/preference I don't use these elements
>anyways. However without a correct document model, all instances derived
>thusly can and may be utilizing irrelevant, unneeded, or unwanted
>content simply because they are a part of the original xml markup language.
>
>As one of the editors once stated offlist, I am one of the seemingly few
>people who likes XML Markup. So I tend to see the project from another angle.
>Whether that's good or bad I am not sure yet.
I agree here, too. My perspective is from a different angle.
Just because an element's not listed doesn't mean we don't use it. The
<sectN> guidance was created to make docs more modular, and it has
proven worthwhile several times for me personally. The ease of
transmuting docs received with <sectN> just using some simple sed lines
means no one has to break a sweat even if a writer uses that element.
For any elements that need special guidance for FDP, that's what the
Documentation Guide is for.
I would counter (politely, of course:) this argument by claiming that
eliminating unused elements makes the problem go away. poof.
I'm with Tommy on this one; defining this (a) takes energy away
from
docs and puts it toward unnecessary process,
This statement assumes that, say, Thomas (& others possibly involved in
the dtd project) would be otherwise working on something else. It's not
clear to me that this is necessarily the case. Maybe the dtd folks only
wanna work on dtds...
OTOH, deciding on precisely which subset is to be the official fdp dtd
would require some effort from those outside the dtd project. In that
sense the project would indeed take energy away from other parts of the
project.
and (b) creates a need for
additional documentation when DocBook is already covered.
I don't understand how making DocBook simpler (i.e. smaller) creates a
need for additional documentation. Seems to me that the notion that the
writers can use *every* tag available simplifies the documentation
needs. IOW, it eliminates the need for "don't use these tags...".
If we had
hundreds of volunteer doc monkeys typing away, I would say go for it,
but when we're still trying to put together the basis, it's probably not
time for this.
I'm actually neutral on this general argument/discussion, (despite my
above comments), but I would like to say that if someone (i.e. Thomas)
is willing to take this on, it might lessen the learning curve a bit for
new authors. (whoops. /me already said this)
But it's worth keeping in mind for some future time when
those armies of doc monkeys *do* show up... :-)
And when they do, they'll no doubt be flying...
:-)
Cheers,
Mark
--
----------------------------------------------------------
Mark Johnson <mjohnson(a)redhat.com>
OS Product Documentation
Engineering, Red Hat, Inc. <http://www.redhat.com>
Tel: 919.754.4151 Fax: 919.754.3708
GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242