OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

relax-ng message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Subject: RE: Two things to strengthen the spec

James Clark wrote:
>I'm not sure I agree with Murata-san that the spec is only for developers
>and language designers. I would also like to see it accessible to "advanced
>users", users who want to understand the finer points of the language, and
>also to educators and authors, people who are going to explain the language
>to others, and perhaps write their own tutorials.

I think this is a reasonable, accurate assessment of who may really read
this spec.

>More examples would probably a good thing even if the audience was only
>developers and language developers. Personally I find even rigourous specs
>are easier to understand with some examples. I have never heard of anybody
>complaining of too many examples in a spec.  I recognize it is a fault in
>my spec writing that I tend to put too few examples in.

I think your spec writing is clear and even at times elegant. Examples will
just give your the spec a boost.

Examples give readers something to imitate. This allows them to do something
immediately without understanding the fine details. This is how we learned
as children. We also learn by making approximations and comparisons.
Examples help us do that. Examples also restate the prose which, in a sense,
helps fulfill a fundamental principle of rhetoric: "Tell them what you are
going to tell them. Tell them. Then tell them what you just told them."

>I repeat my request to Mike. Where in the spec do you think examples would
>be most useful? Where in the spec do you have problems understanding
>without examples?

For now, I will note several places in a separate mail coming soon to a
RELAX NG list near you. I will also reread the July 18 version of the spec
with a highlighter to pinpoint all areas (imo) where examples may help.
(This may take a few days.)


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC