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

[Dan Vint <dvint@slip.net>]

I know that one area that usually throws me is trying to figure out the context 
or the use of something. Let me pick on XSLT first. They start out with a
section on Fallback but never really provide a defintion of what this means to
them. I don't think I have ever come across this as a Comp Sci term so what is
the general meaning of this facilty. After getting into and reading the section
twice (after getting through the whole spec to find the other references to 
issues and features about this) you get a feel for what it is meant to be used 
for, but still no clear definition.

With Schemas, the primer is a good start, but again it lacks the defintion and
explanation of why I might want a feature. There is no context really provided
that says, we wanted to improve DTDs, and here are the 5 (more likely 100) 
things that we wanted to change and improve. If even that simple list was 
provided and features linked back to the "requirement" that they were being
implemented to solve it might help with the understanding. Instead we jump
into what feels like the middle of the process and get this laundry list of 
features.

It would be nice if some consistancy in presentation was preserved. XSLT and
Schemas have a similar background in that what we have are element definitions
that have attributes that need to be explained. Why do I have two different way
of presenting the information? In XSLT I see the actual psuedo XML for the
various elements, in Schemas we get this table that talks about properties.

In just checking the Glossary in the structures spec, I see that it hasn't
even been built yet. How many versions has this document gone through? The
simple effort of making sure that this was provided and accurate would make 
reading this spec off line a little more manageable.

Anyway, enough rambling from me ...

..dan

> 
> Linda van den Brink wrote:
> 
> > Whereas a tech writer, who is inside
> > the organization, would presumably have good communication lines to the
> > editors of specs and could ask them 'what is meant here' and THEN come up
> > with a good rewrite.
> 
> So would people be happier with
>   * a much more comprehensive Primer
>   * splitting the Structures draft into two or three parts that were
> more
>      self contained
>   * a much terser algorithmic/logical treatment of the subject, less
>      comprehensible to Joe Database but smaller and more precise
>   * a rewrite of structures based on the concrete syntax rather than
>       having the abstract components first
> 
> Knowing some specifics might be helpful.  
> 
> Even knowing at what point you become confused might help: I know 
> paragraph clarification is not Simon's preferred way, but it is
> not a waste of time.  
> 
> Cheers
> Rick Jelliffe
>