Re: DSSSL Documentation Project?

[Tony Graham <tgraham@xxxxxxxxxxxxxxxx>]

At 11 Jun 1997 04:52 -0400, Paul Prescod wrote:
 > Yes, I would like to see a glossary, beyond the one provided in the
 > DSSSL spec.

It seems to me that a glossary is a good place to start.

 > But overall (not just relating to the glossary spec) I wonder if a
 > volunteer effort can be as organized and comprehensive as we have been
 > discussing. Perhaps our first goal should be to get a single, complete
 > tutorial done. I don't know that we necessarily need committees and
 > formal editors and so forth. "The Internet" seems to be a fairly careful
 > editor as long as each chapter remains under the change control of
 > someone willing to maintain it. I just suggest this because I don't know
 > if we will have enough person-power for formal editors and committees.

On the contrary, I think we can be organized and comprehensive.  I
don't think we're going to be organized and comprehensive right away,
but I think it can be done.  "The Internet" also hosts some very
impressive collaborative software projects (the Apache web server
comes to mind), and collaboratively writing software like that must be
a whole lot harder than being organized and comprehensive about
writing documentation.

I don't know what the final process will be.  This whole discussion is
only three days old, remember.  I'm trying to get people's ideas,
yours included, about what can and should be done.  We have some good
ideas already, but that doesn't mean we don't need more input from
more people.

I'm talking about committees because I think it could become more than
one person can handle (and that the person handling it should have
time for other things) and because the whole thing shouldn't go on
hold if "The Coodinator" goes on vacation or has to meet a deadline in
their real job.

I'm talking about committees because this shouldn't be seen as Tony's
(or anybody's) DSSSL Documentation Project.  This is supposed to be
another "DSSSL users helping other DSSSL users" thing, and having more
than one hand at the wheel will help avoid misconceptions.

I'm talking about committees because two (or more) heads are often
better than one.  I hadn't thought about starting out with a glossary
or FAQ, and that's not going to be the last time someone else's idea
is better than mine.

I'm talking about editors because, if this goes the way of lots of
people contributing lots of small pieces, then we need to think about
continuity and the big picture as well as correct punctuation and
grammar.

I'm talking about review before publication because that will make
better quality documentation.  It's the 80-20 rule in action -- a
review will find 80% of the errors in 20% of the time whereas if you
just put it out on "The Internet", you'll hear about the same 80% of
the errors from 80% of the recipients (and it's the 20% who don't
catch the error or don't know to upgrade the documentation that you
really have to worry about).

I have overstated the case to make a point, I know, but I think a
review before publication will save a lot of updates.  You beta test
software before making it public, why not beta test documentation?

I also don't know what the review process should be.  I don't even
know if reviewing and editing are one thing or two.  Among the
choices are assigning reviewers, having a pool of reviewers, or just
putting a draft in a semi-private place for everybody on the list to
look at.

 > Depending on the final copyright, I will donate my existing materials
 > (after I do my own edit and update of them). I'm not comfortable with
 > having my materials appear in someone's DSSSL book next year --
 > especially if it is just a printed version of the results of this
 > project sold for $50.00. My information doesn't want to be THAT free.

Your tutorial would be a very useful contribution, thank you.

Copyright, of course, is another unresolved issue.  Does anyone have
any suggestions or experience?

I, too, wouldn't want whatever we produce to appear in someone else's
DSSSL book.  I wouldn't know what to do if someone offered to make a
book of just our documentation.  There's also shareware CD-ROMs to
consider and, for all I know, CD-ROMs in the backs of original books
about DSSSL.

What DTD are you using?

Assuming the copyright issue is solved, what would be the logical next
step to complement or expand upon your tutorial?

Are you open to assistance in expanding your tutorial?

Writing a complete tutorial is a BIG chunk of work.  I'm still casting
around for a way for people without an equivalent amount of time and
energy to still be able to contribute to the project, hence the talk
of a glossary, FAQ, or cookbook.  Where do you see people with limited
time being able to contribute to the effort?

Regards,


Tony Graham
=======================================================================
Tony Graham, Consultant
Mulberry Technologies, Inc.                         Phone: 301-231-6931
6010 Executive Blvd., Suite 608                     Fax:   301-231-6935
Rockville, MD USA 20852                 email: tgraham@xxxxxxxxxxxxxxxx
=======================================================================


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