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

[Ronald Bourret <rpbourret@rpbourret.com>]

In a previous post, I said:
> 
> Rick JELLIFFE wrote:
> 
> > So would people be happier with
> >   * a much more comprehensive Primer
> 
> I agree with Miloslav on this one. The primer is a stop-gap and if you
> fixed the spec, you wouldn't need it. I think a better idea would be to
> mix the primer with the regular spec (see Examples, below).

and:

> >   * a much terser algorithmic/logical treatment of the subject, less
> >      comprehensible to Joe Database but smaller and more precise
> 
> Definitely the wrong direction. This would, on the other hand, be a very
> useful thing to throw into an appendix, with a note that if the appendix
> disagrees with the rest of the spec, the appendix is right.

I would like to plead semi-advanced brain death.

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

One of the problems with specs is that they are primarily reference
material, but generally have a bit of user's guide thrown in. It is
therefore generally very difficult to learn about a topic from a spec
alone -- sort of like trying to figure out what a puzzle looks like by
only viewing the pieces. For ISO/ANSI/etc. specs, this isn't much of a
problem. These usually come after the fact, and people read them for
details: they already know the big picture, having usually had years of
experience. If not, there are plenty of books around to get them going.

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.

In some cases, the ground covered by the spec is conceptually simple
enough that a short introduction/overview in the spec gives the reader
enough information to wade through the details. The XSLT and XML specs
are good examples of this (XSLT especially).

Therefore, my suggestion to pitch the primer now strikes me as idiotic
-- in fact, it's the ideal situation and provides material to get people
going, which is exactly what they need. Similarly, my suggestion to
merge the primer into the structures spec strikes me as equally idiotic
-- all it will do is make the structures spec harder to use as reference
material, as somebody pointed out last week.

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.

Lapsing towards early senility,

-- 
Ronald Bourret
Programming, Writing, and Training
XML, Databases, and Schemas
http://www.rpbourret.com