Re: DSSSL Documentation Project

Subject: Re: DSSSL Documentation Project
From: Tony Graham <tgraham@xxxxxxxxxxxxxxxx>
Date: Tue, 20 Jan 1998 14:16:14 -0500 (EST)
At 20 Jan 1998 00:38 -0500, Paul Prescod wrote:
 > Ben Trafford wrote:
 > >         I've had massive problems trying to use DSSSL with clients because of
 > > the lack of adequate documentation. I've also seen major software
 > > developers turn down the use of DSSSL because of that same lack. Look at
 > > what the Linux Free Documentation Project did for that platform! We
 > > could do the same for DSSSL.
 > 
 > Note that the Linux Documentation Project did not write a book. They
 > essentially wrote many short tutorials and used hyperlinks and a central
 > index to glue them together.
 > 
 > I am less confident than I was last year that it is feasible to write a
 > long, complicated, 21 chapter book over the Internet, using volunteers
 > and get something coherent out the other end. I'm also not as convinced
 > that we want to compete with prospective book authors like Ken. I am not
 > writing a DSSSL book, but I hope someone does.

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.

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.

This whole thing started because I figured that there were many people
capable of writing good, useful stuff about DSSSL but that precious
few of them had the time or resources to write a complete book.  I am
still of that opinion.

At SGML/XML'97, I talked to two people who had told me back in June
that they were writing DSSSL books.  As of December, neither of them
had had the spare time to get very far with their books.  I do wish
them well with their writing, but I think this illustrates my point.

 > I think that a more achievable goal would be to use the handbook outline
 > as a list of documents we would like completed, as the Linux people do.
 > We should then just link to the documents in the places where they
 > currently live. For instance, the first half part one is essentially my
 > tutorial (except I didn't write about the transformation language). 

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.

 > To complete "part one" we just need a crash course on Scheme (which I
 > think we can find on the web) and some annotated complex stylesheet
 > examples (which someone can do over a weekend). My argument is
 > that things get much easier if you just use them where they are. It also
 > keeps issues of ownership simple, cuts down on email attachment hassle,
 > might allow for some creative competition and avoids conversion to One
 > True DTD (which I have been putting off before submitting my tutorial to
 > the project).

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 think DocBook is a sensible choice because
it is designed for software documentation and has elements like
<programlisting>, <replaceable>, and <synopsis> as well as book-like
elements like <chapter>, <preface>, and <legalnotice>.  It makes
additional sense for use with DSSSL because we already have, thanks to
Jon Bosak and Norman Walsh, comprehensive and well-designed DSSSL
stylesheets for both print and HTML output from the DocBook DTD.

 > As far as part 2, the two syntax summaries are essentially already done.
 > Debatably the spec. is its own refernce for many of the parts. It might
 > be most productive to zero in on the things people find most confusing.
 > 
 > Part 3 seems very important to me, and could be handled either as an
 > "Advanced DSSSL Tutorial" or as a series of tutorials (the Linux project
 > calls these "HowTos"). In the short term, I think that the absolute
 > highest priority should be chapter 21 which describes how to use the
 > Jade SGML back-end to do SGML->SGML transforms. People want to use Jade
 > for web pages and I get questions about how to do that every few weeks
 > in email. A good tutorial on this would go a long way and would not be
 > very long.

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?

 > I'm not suggesting we dissolve the project or anything like that, but
 > rather consider its main goal to be a *series* of tutorials and
 > reference manuals, maintained by their individual authors, which taken
 > together describe DSSSL as the various documents in the Linux
 > Documentation Project describe Linux.

I have always hoped that the individual authors will maintain their
contributions.  I'll have to look at what I've said before, but I
don't think that we're as far apart on this as you think, Paul.

Regards,


Tony Graham
=======================================================================
Tony Graham
Mulberry Technologies, Inc.                         Phone: 301-315-9632
17 West Jefferson Street, Suite 207                 Fax:   301-315-8285
Rockville, MD USA 20850                 email: tgraham@xxxxxxxxxxxxxxxx
=======================================================================


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


Current Thread
  • Re: DSSSL Documentation Project, (continued)
        • James Clark - from mail1.ability.netby web4.ability.net (8.8.5/8.6.12) with ESMTP id WAA21824Mon, 19 Jan 1998 22:50:58 -0500 (EST)
        • 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)