Re: DSSSL Documentation Project

Subject: Re: DSSSL Documentation Project
From: Paul Prescod <papresco@xxxxxxxxxxxxxxxx>
Date: Tue, 20 Jan 1998 16:15:23 -0500
Let me state first that I have no doubt that the goal of a coherent,
consistent online DSSSL text is more appealing than that of an
affiliation of tutorials.

Let me phrase my suggestion another way: perhaps our first goal should
be *coverage* of the entire DSSSL language rather than *linear
coherency* of coverage. If we get coverage alone (with some overlap,
some false leads, some missing links, etc.) then we will have
accomplished something great. We could then refashion our texts into a
coherent whole. Yes, this way takes more work, but it increases the
possibility of us reaching the first level, which we did not the last
time we attacked the problem.

If we have the enthusiasm and time to pull off coherency and consistency
in one shot, then great. But let's go into the venture with eyes wide
open.

Tony Graham wrote:
> 
> We developed an outline first so that we could be coherent and reduce
> the overlap in what various people wrote.  Right now we have more than
> 400 potential reviewers reading this list, and I expect that if
> something is not coherent or not consistent, then someone will point
> it out;  I don't think coherency is our problem.

I'm happy to be proven wrong. I just tend to think that technical
writing has many of the same problems as software development.
Organizing 10 people to write a 20,000 line computer program is much
more work than asking them each to write a single 2,000 line program.
Jade is made up of modules, but I don't think it would have been
developed if 10 C++ knowledgable programmers had set out to each write a
module. The "Mythical Man Month" problems would compound the problems of
distributed development and volunteer initiative.

Documents are more linear, which makes things a little easier, but there
are still alot of connection points between them (where is this term
defined, how do these concepts relate, etc.) and in my experience,
maintaining those is hard. On top of the literary challenges, there are
the problems of learning/installing the standard DTD, sending updates to
the maintainer, routing commentary to the right person, updating in
unison as information changes and so on. The LDP has an advantage over
us because Linux is way too big and complex for them to even *consider*
a single book that covers it all. Rather there are many books and
tutorials, each written by a single author.
 
> With no disrespect to Ken, just because Ken has said that he is
> writing a book on DSSSL doesn't mean that a group of us can't also
> write a book on DSSSL.  The fact that someone once wrote a book on
> HTML doesn't seem to have stopped other people also writing books.

True enough. Competition with print authors is just another issue to
consider. It isn't a killer argument.

> Having documents scattered around the web makes the most sense if you
> have a fast, permanent Internet connection.  Sometimes you want a
> local copy because you're not always connected or you connect only
> through a thin pipe, and for some people a lot of the time paper is
> better.

I agree.

> As I understand it, Linux documentation uses the "LinuxDoc" DTD and
> toolset, and that "LinuxDoc" tools have since been renamed
> "SGML-Tools".  Marking up the DSSSL documentation with a single DTD
> makes the same sort of sense as standardising the Linux documentation
> did to the Linux folks.  

I believe in standards as much as the next person. I also believe that
adhering to them is more work. Like the rest of you, my "day job" is
encouraging organizations to make that investment. But I also get paid
to tell them when they should consider backing off, rather than risking
failure. Again, if we agree that we have the energy to do the whole
thing, great. I'm a natural pessimist.

<ASIDE>The LDP seems to use LaTeX for some or most of their larger
documents: http://sunsite.unc.edu/mdw/LDP-Manifesto.html . I'm not a
very big fan of SGML-Tools, so this doesn't bother me very much. Perhaps
a good project for this mailing list would be making the DocBook
stylesheets and Jade as easy to use and widely distributed as the
SGML-Tools.</ASIDE>

> Since you don't appear to have that already but do know what it is
> that people want to know, do you want to write it?

Yes, I can write that, whichever way we decide to go. But I know myself
and I know that I will probably write it sooner if I know it is merely a
matter of building on my own tutorial, in my existing DTD and putting it
on my website rather than figuring out what DocBook elements to use,
submitting to reviewers, waiting for comments, updating, resubmitting,
comparing to other's parts, making links etc. etc. Every round of
communication provides another opportunity for me to procrastinate. :)

 Paul Prescod
--
"You have the wrong number."
"Eh? Isn't that the Odeon?"
"No, this is the Great Theater of Life. Admission is free, but the 
taxation is mortal. You come when you can, and leave when you must. The 
show is continuous. Good-night." -- Robertson Davies, "The Cunning Man"


 DSSSList info and archive:  http://www.mulberrytech.com/dsssl/dssslist


Current Thread
  • Re: DSSSL Documentation Project, (continued)
        • Ben Trafford - from mail1.ability.netby web4.ability.net (8.8.5/8.6.12) with ESMTP id XAA22068Mon, 19 Jan 1998 23:03:23 -0500 (EST)
        • Paul Prescod - from mail1.ability.netby web4.ability.net (8.8.5/8.6.12) with ESMTP id AAA27805Tue, 20 Jan 1998 00:39:06 -0500 (EST)
        • Ben Trafford - from mail1.ability.netby web4.ability.net (8.8.5/8.6.12) with ESMTP id MAA07746Tue, 20 Jan 1998 12:10:14 -0500 (EST)
        • Tony Graham - from mail1.ability.netby web4.ability.net (8.8.5/8.6.12) with ESMTP id OAA09037Tue, 20 Jan 1998 14:18:29 -0500 (EST)
        • Paul Prescod - from mail1.ability.netby web4.ability.net (8.8.5/8.6.12) with ESMTP id QAA10066Tue, 20 Jan 1998 16:19:36 -0500 (EST) <=
        • Steve Roggenkamp - from mail1.ability.netby web4.ability.net (8.8.5/8.6.12) with ESMTP id RAA10560Tue, 20 Jan 1998 17:15:05 -0500 (EST)
      • Tony Graham - from mail1.ability.netby web4.ability.net (8.8.5/8.6.12) with ESMTP id WAA21409Mon, 19 Jan 1998 22:16:24 -0500 (EST)
        • Ben Trafford - from mail1.ability.netby web4.ability.net (8.8.5/8.6.12) with ESMTP id WAA21586Mon, 19 Jan 1998 22:25:49 -0500 (EST)
    • Pawson, David - from mail1.ability.netby web4.ability.net (8.8.5/8.6.12) with ESMTP id EAA04071Tue, 20 Jan 1998 04:26:37 -0500 (EST)