Fedora DTD?

[Mark Johnson]

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 at 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 at 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