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

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.

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

--On 17 July 2001 17:19 -0700 Michael Fitzgerald <mike@wyeast.net> wrote:

> If the audience is *only* implementers and developers, you should state
> that clearly in the abstract or prolog of the document and send others to
> the tutorial with a link because many other people besides implementers
> and developers will attempt to read this spec.
> If you intend this document for implementers and developers only, I will
> withdraw my suggestion to add more definitions and additional markup
> examples, as long as you direct less sophisticated readers to the
> tutorial.
> I think the spec is clearly written and works well. If you want to reach a
> broader audience, though, I think you can do that easily by adding a few
> ornaments.
> I don't want to see the kinds of complaints about other specs laid at the
> feet of RELAX NG as well, but this can be obviated by a clear warning:
> "Users: GO BACK! Go back to the tutorial while there's still time!!!"
> Mike
> -----Original Message-----
> From: Murata Makoto [mailto:mura034@attglobal.net]
> Sent: Saturday, July 14, 2001 11:46 PM
> To: mike@wyeast.net
> Cc: RELAX NG List
> Subject: Re: Two things to strengthen the spec
>> Who is your perceived audience for the spec? Implementors and developers
> only? Or do you
> see a broader range of readers?
> Implementors and developers only.  Users read tutorials.   I think that
> our tutorial
> is already very helpful.
> Cheers,
> Makoto
> ------------------------------------------------------------------
> To unsubscribe from this elist send a message with the single word
> "unsubscribe" in the body to: relax-ng-request@lists.oasis-open.org

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

Powered by eList eXpress LLC