Re: DSSSL Documentation Project?

[Tony Graham <tgraham@xxxxxxxxxxxxxxxx>]

At 10 Jun 1997 08:15 +0000, David Pawson wrote:
 > >>> Tony Graham <tgraham@xxxxxxxxxxxxxxxx> wrote 
 >  -snip 
 > we are still lacking the
 > "reliable reference with lots of worked examples" and, I would
 > hazard, we are still lacking sufficient entry-level material.
 > 
 > - again, wholehearted agreement.
 > Those of us unable to source it could, perhaps, assist 
 > with collation / editing.

Thank you, I certainly hope people can and will assist with editing
and the like.

 > Given a location for posting (is it inappropriate for the list,
 > particularly once it becomes sizeable?) I would volunteer
 > to edit some part of it. If a dozen of us came up with
 > a section each, we could have it in place within a few
 > months,
 > leaving the clever bit - generating the material in bits,
 > to those more suited to that work. The analysts / 
 > detail merchants could then pick the bones for errors / 
 > omissions _with_ improvements.
 > 
 > Any other takers?
 > <1> For a section
 > <2> A home for it (hint to Mulberry!)

I have already offered the Mulberry web site (and, by extension, the
ftp site as well, I guess) as the home for this work.  As with the XS
discussion, we could move the documentation project discussion to a
new list if it looks like swamping the DSSSList.  I wouldn't move it
yet because we don't know what we're doing, how we're going to do it,
or exactly who will do it. (But, as ever, if you have comments on the
direction of the DSSSList, you can send mail to
dssslist-owner@xxxxxxxxxxxxxxxx).

 > The proposed contents list appears to be a starter for 10?

True, but is there anyone willing to throw out John Fieber's outline
(no offence, John) and come up with one of their own?  Is there a
consensus that that sort of book is a good place to start?  Is that
all that is required?

I am hoping we define a structure where people can contribute a small
part (say the node-list-first page, the leader flow object class page,
or a cookbook item) if that's all they have time for and where others,
should we be so fortunate, are able to contribute larger or more
complex sections such as an introduction to groves.

My present thinking is to work out what we want to do, define its
structure in more detail, then let people (or groups of people) to
propose more detailed outlines for the parts they volunteer to do.
Once a part is complete, we would then make it available for other
people to volunteer to review and edit it.  From there it would go for
approval for inclusion by some sort of editorial committee in charge
of keeping the whole thing on track and/or approval or comment by the
whole of the documentation project people.

Little things missing from that picture are:

 - what DTD to use

 - whether to write in SGML or XML

 - the stylesheets

 - the templates or style guidelines so people can be consistent

 - the rules for accepting or rejecting offers to write, offers to
   review, and the parts themselves

 - copyright

 - picking some sort of steering committee

 - the timeframe within which we want to complete something.

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