Re: DSSSL Documentation Project

Subject: Re: DSSSL Documentation Project
From: Paul Prescod <papresco@xxxxxxxxxxxxxxxx>
Date: Tue, 20 Jan 1998 00:38:15 -0500
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.

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). 

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

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.

 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:

Current Thread
  • Re: DSSSL Documentation Project, (continued)
    • Paul Prescod - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id NAA18530Mon, 19 Jan 1998 13:30:15 -0500 (EST)
      • G. Ken Holman - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id UAA20929Mon, 19 Jan 1998 20:34:51 -0500 (EST)
        • James Clark - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id WAA21824Mon, 19 Jan 1998 22:50:58 -0500 (EST)
        • Ben Trafford - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id XAA22068Mon, 19 Jan 1998 23:03:23 -0500 (EST)
        • Paul Prescod - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id AAA27805Tue, 20 Jan 1998 00:39:06 -0500 (EST) <=
        • Ben Trafford - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id MAA07746Tue, 20 Jan 1998 12:10:14 -0500 (EST)
        • Tony Graham - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id OAA09037Tue, 20 Jan 1998 14:18:29 -0500 (EST)
        • Paul Prescod - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id QAA10066Tue, 20 Jan 1998 16:19:36 -0500 (EST)
        • Steve Roggenkamp - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id RAA10560Tue, 20 Jan 1998 17:15:05 -0500 (EST)