Re: DD: Modularity guidelines

Subject: Re: DD: Modularity guidelines
From: Tony Graham <tgraham@xxxxxxxxxxxxxxxx>
Date: Mon, 16 Jun 1997 02:40:33 -0400 (EDT)
I'll only reply to a portion of Frank's excellent post.

At 16 Jun 1997 12:14 +0900, Frank Christoph wrote:
 > Lastly, I want to suggest that someone write up a set of goals and guidelines
 > for this project.  Even with a list of topics at hand and the assurance that
 > someone will edit your work afterwards, it can be difficult deciding which
 > tack to take on a topic without having the overall goals made concrete in
 > plain English.  (Think of it as a manifesto.)  As far as I can determine,
 > the goals and guidelines of the project are:

I had thought I could start on describing the big picture by looking
at everybody's mail on the subject, but I haven't got to it yet.  Even
so, this is not just my project, Frank has made a good start, and
input from everybody is welcome.

I volunteer to write the goals, but I welcome collaborators (and
ghostwriters such as Frank, since you can expect to see some of his
points in whatever I would write).

 >   * To promote and encourage the use of DSSSL by providing to the public
 >   [cost-free] explanatory and reference material above and beyond that
 >   contained in the standard

I'd like to see "cost free" or "cost-free for non-commercial use"
included.

I would also add:

     * To make it possible to contribute in a small way

     * To ensure that the material is accurate and that errors and
     omissions are corrected in a timely manner

 >   * The material will complement the standard, not replace it, i.e., the
 >   topics will be expository (descriptive), rather than prescriptive.  For
 >   example, if someone describes a way to do indexing or footnotes, it should
 >   either be presented with other possible implementations, or as a sort of
 >   programming idiom.  [On the other hand, it might be good to encourage
 >   the use of such idioms --- when we are sure that a particular implementation
 >   is adequate in most cases --- by collecting them into a "DD Style Spec"
 >   which would provide, e.g., footnotes and indexing to client specs, and
 >   to distribute this as well.]

I expect we'll be providing stylesheets along with the documentation
anyway.  Do you want to take the "DD Style Spec" a step further and
make a list (or data dictionary) of commonly used variable names, such
as "%title-font-family%", so it's easier to merge stylesheets?
[Personally, it's far down on my priorities.]

 >   * The material will assume the reader has a working knowledge of SGML.
 >   It will not assume a familiarity with alternative SGML formatting methods,
 >   except when the topic explicitly concerns such alternative methods.
 > 
 >   * [Topics will be written in a style that assumes complete knowledge of
 >   the standard at a beginner's level, except for knowledge of that topic
 >   and its dependents.  If a topic assumes a great deal of auxiliary knowledge,
 >   though, the auxiliary topic should be cross-referenced (and it really
 >   ought to be cross-referenced in less critical case as well, perhaps).]

This seems to assume we're doing a one-size-fits-all document.  For
example, it's a bit hard for a tutorial to assume "complete knowledge
of the standard at a beginner's level", and it may be hard to do a
good description of colour spaces at a beginner's level.

If we do the beginner part properly, then there will soon be people
wanting something more, not to mention the people already using DSSSL
who could benefit from having examples and cookbook tips.

This touches on an idea I haven't fully worked out for myself: to what
extent does "The Project" mandate what gets written or included?  I
don't think we can mandate anything, really.  This is a cooperative
effort, and if people don't want to write something, they don't have
to.  Our goal should be to collect ideas, put people who want to work
on the same thing in touch with each other, and provide a place to put
the results.

We may be able to make a "Most Wanted" list of subject areas or types
of documentation (or stylesheets) or outline the structure of a
document, and the range of people able to contribute may mean we can
cover most things, but if someone offers something not on our list, we
shouldn't automatically turn them away.  We should also be able to
cope with some duplication of material (for example, two tutorials on
the same subject that take different approaches), but I would expect
that people would see the gaps in the mosaic and work to fill them.

There may also be a role for a public archive for DSSSL-related
material that doesn't happen to be part of our effort, such as an
archive of stylesheets for publically available DTDs, but I think
that's outside our scope.

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


Current Thread