DD: Modularity guidelines

[christo@xxxxxxxxxxxxxxxxxx (Frank Christoph)]

I want to suggest a guideline for documentation based on modularity.  Perhaps
everyone has already taken this as a given, and it is simply my inexperience
with writing documentation that prompts me to mention it; but maybe it is
worth addressing anyway.

The more I think about it, the more obvious it sounds, but: essentially, let's
keep the entries as focused as possible, and implement relations between
topics by means of cross-references.

For example, if someone is writing a subject-oriented entry as I suggested
earlier (a description of modes, say) the writer should not attempt to explain
the syntax or semantics of the expression language.  Undoubtedly, a lot of
readers who are new to DSSSL will already be familiar with Scheme, and it
would be a waste of their time (and the writer's) if such partial explanations
accompanied every documentation fragment.  Of course, there is nothing wrong
with having a section on the expression language --- as long as it's separate.

Conversely, let us avoid assuming extraneous knowledge as well.  For example,
one might think to explain a feature of DSSSL by comparing it with a feature
of CSS, but all readers will not be familiar with CSS.  Such comparisons
would, I think, be useful, but they would be more useful if they were
encapsulated separately.

Assorted other things:

John Fieber has already suggested an outline for task-oriented concerns, i.e.,
"How do I do A?"  I suggested some subject-oriented topics as well.  For the
latter case, why don't we follow the structure of the standard, and head up
(or end) each section with an executive summary and a table of function
signatures (indexed by clauses from the standard) and syntactic forms
(indexed by their production numbers in the standard)?

And, here are some further suggestions for topics which occurred to me during
the writing of this letter:

  * Comparisons (perhaps written in the style, "if you know X from CSS, then
    you know F(X) in DSSSL")

    * expression language vs. Scheme
    * DSSSL vs. CSS
    * DSSSL vs. FOSI

  * List of implementations

    * Jade
    * SENG/DSSSL (?) from Copernican Solutions

  * What is the point of a DSSSL specification being an SGML document itself?
    (This would touch on the idea of compound specs, libraries of specs, and
    the rule that the first occurrence of a definition wins in case of
    duplicates, but that duplicates must be in different parts.)

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:

  * 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

  * 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.]

  * 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).]

I enclosed in brackets some things that others might find questionable.  The
last paragraph is what I suggested about modularity at the beginning of this
letter, so it is entirely in brackets.  But, as far as I can tell, everyone
agrees on the remaining ideas.  Please correct me if I'm wrong, and add more
goals/guidelines if you can think of any.

---
Frank Christoph                 Next Solution Co.      Tel: 0424-98-1811
christo@xxxxxxxxxxxxxxxxxx                             Fax: 0424-98-1500

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