Re: DSSSL Documentation Project

[Paul Prescod <papresco@xxxxxxxxxxxxxxxx>]

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:  http://www.mulberrytech.com/dsssl/dssslist