[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: if SGML is so great...

Mr. Preckshot has a point.  There are people, who may be potential
contributers, who aren't going to care about docbook.  It doesn't matter
that it's "not that hard" to learn.  Some people simply have other

If you feed them just enough docbook for them to get by, the truth is
that you're not going to get any of docbook's benefits anyway...  a pile
of <simpara>'s won't do a whit for your intelligent search engine.  Just
like everything else, docbook's benefits aren't free.  

Now I've been up and down Norm's docbook guide, marked up a handful of
pages of my own, and I still find myself turning again and again to the
reference to ask "is that tag in this markup language, or the other
one?"  "Do they have a tag for this exact thing, or do I use a more
general one?"  "Is this tag depreciated?" etc, etc.  It slows down the
writing.  So I can understand why someone without the indexing fetish
wouldn't find it worth their while.


Fortunately for the spiders and searchers of the world, there are a
number of people with the indexing fetish who will gladly take a
plaintext document and put the markup on it for you.  The last time
someone asked for help with this on the Open Source Writer's Group list
[1] (I think it was for the "Replacing NT with Linux HOWTO"), no less
than four volunteers signed up to help with the transition.

No, it's not optimal having someone do the markup who doesn't understand
the material as intimately as the author does.  And the author won't get
off scott free either, e'll probably have to field questions like "Is
this a system command, or an application name?".  But it sounds like a
good deal overall.

 - Kevin

[1] Open Source Writer's Group (OSWG) http://www.oswg.org/
    ...which is, uhh, down for the time being, while the webmaster and
    her cat flee the country, but it'll be up again before long.
    Basic idea is that these are people who can write, edit, learn
    docbook, etc, who want to help make documentation happen.  So if you
    have authors who, as writers, need support in turning their
    knowledge into a complete document, you should be able to direct
    them there.

Kevin Turner <acapnotic@users.sourceforge.net> | OpenPGP encryption welcome here
This mailing list is archived at...  
 error: archive at www.linuxdoc.org is not navigable (page too large).
please apply at geocrawler.com, mail-archive.com, or marc.theaimsgroup.com

To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org