xml-dev - Re: Improved writing -- who's going to pay for it?

[Robin Cover <robin@isogen.com>]

> Date: Sun, 15 Oct 2000 14:29:00 -0700
> From: Ronald Bourret <rpbourret@rpbourret.com>
> To: xml-dev@lists.xml.org
> Subject: Re: Improved writing -- who's going to pay for it?

Though reluctant to add to an already overworked and
protracted plurilog on standards writing, I would say in
support of Ronald Bourret: 

> I would like to plead semi-advanced brain death.

I detected no early senility, but a welcome reminder of
principles (maybe axioms) I learned were foundational
to software engineering, and transferrable to formal
specification (standards) development/publishing.

> Traditional documentation is split roughly into user's
> guides (which give the big picture and walk you through
> the most important details) and reference material (which
> give all the details in fairly terse form).

The analogy seems fitting to me.  But an important observation
is that online/electronic documents liberate us from some of
the constraints which (in paper-print) hitherto required
separate documents for "reference" and "user guide."  We can
use transclusion (or weaker normalized strategy) and
hyperlinking to accommodate a wide variety of learners --
using "views" along with reader profiles.  Tim Bray modeled
this in the annotated XML spec (Bob DuCharme in a less
versatile way through a paper-print analog).  Far more can
be done using currently-available publishing platforms.

Using hyperlinks and filtered views (graded to the match the
reader's background and reading objectives), it's possible to
combine the spec and the tutorial in a single publication for
end-user documentation.  Start with user profiles and a
matching taxonomy of link types. Superior pedagogical strategy
may dictate altering the order of presentation in the
tutorial/primer/guide (vis-a-vis the spec's fixed order) to
match the learning style of the typical non-expert reader.
But with links, order doesn't matter so much: one "clicks" to the
related discussion that stands in the way of understanding
momentarily.  Some learning styles favor starting with a
tutorial linked to the spec, while others favor linking to
commentary from the spec.  Adopting this perspective should
liberate spec writers from the obligation to include too much
"user guide" information in the spec.

The significant question may be whether (e.g.,) W3C believes 
that end-user documentation is part of its mandate, or within its
proper remit. If not, spec writers may still feel the need to put
exposition nominal into the spec itself.

> The W3C is in a somewhat unique position, attempting to introduce new
> material in spec form. This generally frustrates people who are reading
> the spec for the first time, since the spec lacks adequate user's guide
> material and, because the subject is often new, there is no other
> material to read for background.

It's analogous in my view to software development.  The agency
producing the spec should assume responsibility for producing
clear exposition of the formal language.  Another principle
comes into play, however: that software architects and
programmers should not be allowed (much less required) to
produce the general-user-level documentation.  They are too
close to the problem, and too pickled in the jargon that
assumes familiarity with spec-talk discussion.  They cannot
easily disabuse themselves of the kind of knowledge that may
be essential for the newcomer/outsider.  This principle, if
applicable, suggests that W3C would commission and review
user-level documentation written by an "outsider".  Such an
arrangement seems preferable to what we have now: dozens of
publishers wanting to rake in easy money by employing non-
expert writers to produce (quickly!) largely unrefereed works,
which -- in my experience -- typically contain errors of fact
as well as bad opinionated advice that would not pass muster if
it were reviewed by the technical committee producing the spec.

> However, I would like to say that good reference material generally
> does, for each item, contain a sentence or two giving context and
> motivation and a very short example. I do think this would be a good
> idea in the structures spec.

Sure.  Transclude, more or less, according to the reader profile, in
a document designed for outsider consumption.

For what it's worth.

Robin Cover