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

[Miloslav Nic <nicmila@idoox.com>]

Rick JELLIFFE wrote:
> 
> 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

I am afraid this is not a solution. The Primer is already too long for
my liking.
Primer should be a gentle introduction to the basic concepts not a
standard rewrite in 
more normal language. (Or actually it is a solution, write a very
comprehensive
primer, then make it normative and discard the spec :)  )


>   * splitting the Structures draft into two or three parts that were
> more
>      self contained

YES! YES!  YES!  

>   * a much terser algorithmic/logical treatment of the subject, less
>      comprehensible to Joe Database but smaller and more precise

It will probably help some implementators but I am afraid it will not
be of much use to XML Schema users. I am usually reading BNF or similar 
notations as a last resort when I do not see any other option


>   * a rewrite of structures based on the concrete syntax rather than
>       having the abstract components first
> 

YES! YES!  YES!  

I do not believe there are many people who can live on abstraction only.
Abstraction is
superb if you become proficient in the topic and application details
cloud your vision.
But it is much more difficult to directly understand abstraction than to
proceed in few steps
via much more specific and concrete applications.

It is well known in children education, that many mathematical
operations cannot be learnt by 
an average child before she reaches some age. Abstract operations like
division or rational numbers
just cannot be comprehended by 7 years old.

XML was born a few years ago, we are just toddlers in the XML world, we
have different parents and friends, please, be gentle to us. When we
come to age we will appreciate poetry and operas but
now we just want some nice toys to play with.


Or I will start to send the standard authors  manuals how to use a
shampoo based on the
top art chemistry knowledge. Unfortunately, they do not have to read it,
but I have to theirs work.


> 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

-- 
******************************************
<firstName> Miloslav </firstName>    
<surname>   Nic      </surname>     

<mail>    nicmila@idoox.com    </mail>   
<support> http://www.zvon.org  </support>
<zvonMailingList> 
    http://www.zvon.org/index.php?nav_id=4 
</zvonMailingList>