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

[Linda van den Brink <lvdbrink@baan.nl>]

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

I'd vote for a much more comprehensive Primer, at least. Then using a much
terser algorithmic/logical treatment of the subject could also be a good
thing, because Joe Database would also have the Primer to read. Your last
suggestion also sounds good. 
 
> Knowing some specifics might be helpful.  
I must confess I'm one of those "developers sticking to DTDs because the
costs of learning
and implementing schemas still seem to outweigh the benefits. [stLaurent]" 

So I can't really give you specifics. I'm just applying my technical
documentation knowledge to this problem. Insights such as: 
- Writing different documents for different target audiences is good 
- Concreteness is more graspable than abstractness; be concrete when you can
- In a technical design document (like a w3c spec) sacrifice readability to
preciseness

These insights apply here. 

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

Agreed. Only people usually don't respond well when you tell them 'I don't
understand this section of your document, please rewrite'. It works much
better when you can suggest a rewrite. You can do this even when you only
partially understand the subject, but in that case it's usually a good thing
to consult with the writer about the best rewrite. I don't (yet) know how
responsive W3C spec editors are, but I won't hesitate to try. 

Linda
> Cheers
> Rick Jelliffe
>