Re: DD: Suggestions for Coherency

Subject: Re: DD: Suggestions for Coherency
From: Tony Graham <tgraham@xxxxxxxxxxxxxxxx>
Date: Fri, 23 Jan 1998 13:58:09 -0500 (EST)
At 20 Jan 1998 16:35 -0700, Ben Trafford wrote:
 > 	1) I strongly suggest a single organizational editor, and a few editors
 > to check for technical consistency and grammar, etc. Any takers? I'm
 > assuming that Tony Graham would continue in the role of organizational
 > editor, as he's been doing so far. I'm going to delineate this main
 > editor as the editor, and the other editors as proofreaders. 

I'm happy to keep the big picture, but I think the chapter authors can
organise their own outlines, make them available for everyone to
comment, handle their own reviews, etc.  I want to spread the work out
as much as possible to reduce bottlenecks and let people be
responsible for what they're doing.

Sure we'll have inconsistent grammar, not to mention inconsistent
spelling, but that's nothing compared to the fact that we're starting
from near zero.

 > 	2) If we each sent in a proposal outlining the section we intended to
 > write, which could then be organized by the editor for consistency, to
 > avoid overlap, and he could also make suggestions to plug up holes. 

Make your outline publicly available then revise it in response to
feedback, and when the comments from your peers and future audience
slow down to a trickle, you know you have a good outline.

The chapters will be written by people who know what they're talking
about, so they should be able to write a good outline, and public
comment should find the holes and the overlap.

If we do end up with overlap, we'll mediate between the two authors or
set of authors to work out what's best.

 > 	3) After all the outlines are approved, we could move on to actually
 > writing the main documents, which would be submitted to the proofreaders
 > and not the editor, so as to evenly spread out the work. 

Make the drafts publicly available (or available to the list) and be
open to feedback.  The authors are putting their names to their work,
so they will do their best anyway, and anyone using or reviewing their
work is well able to point out what's wrong, inconsistent, or just
awkward.

 > 	4) Once the proofreaders are done with something like a final draft of
 > each section, the editor could return and go through the whole manual
 > for consistency and coherency.

That would happen some time after the Handbook is actually usable.  It
has always seemed to me that much of this would be useful even as
drafts of single chapters.  The modern software development model
seems to be to make your betas available and let the public do your
beta testing;  the same could work for the DSSSL Handbook.

The current Procedures Library is not that comprehensive, but people
have both used what is available and provided feedback and corrections
on the current version.  I also trust that the Glossary, while far
from complete, has also been useful to people.

 > 	5) Voila! Finished product!
 > 
 > 	Perhaps this is oversimplifying, but I think the methodology is sound.
 > So, here's what we would need to implement this idea:
 > 
 > 	1) Main editor.
 > 	2) Five proofreaders (a guess).

Let everybody proof, check, or comment on everything.

 > 	3) A writer for each chapter of the outline. I suggest we start with
 > the proposed DSSSL Handbook. Thus, we'd need a total of twenty-one
 > writers (more or less, depending on overlapping writers). This number
 > would be ideal, as we'd have one person writing each chapter.

Some chapters, such as the descriptions of the flow objects, could be
pretty big.  There's nothing stopping groups of people working on a
chapter.

If a task is divisible, make it known that you want help and see if
anyone has time to help.

 > 	4) An indexer.

Let the authors insert their index hits and we'll rationalise the
index vocabulary after we see what people think is important enough to
index.

 > 	5) Someone to design the actual layout of the manual.

Norman Walsh's (nee Jon Bosak's) stylesheet produces good output as it
is, and it can be customised should that be necessary.

Since we're using DocBook, many other SGML formatting systems already
come with usable stylesheets.

 > 	6) Someone to output the manual in different formats (PostScript, HTML,
 > SGML, etc.)

That should be automatable anyway.

 > 	We also ought to have a set of writing guidelines, methinks.

Maybe in the fullness of time, but not right now.

 > 	So. . .those are my ideas. . .comments and criticisms are welcome, so
 > long as they offer solutions to problems. Just saying "it won't work"
 > doesn't help anybody.

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
  • DD: Suggestions for Coherency
    • Ben Trafford - from mail1.ability.netby web4.ability.net (8.8.5/8.6.12) with ESMTP id SAA11077Tue, 20 Jan 1998 18:29:41 -0500 (EST)
      • Tony Graham - from mail1.ability.netby web4.ability.net (8.8.5/8.6.12) with ESMTP id NAA03495Fri, 23 Jan 1998 13:58:53 -0500 (EST) <=