RE: Example [Was: Two things to strengthen the spec]

[Michael Fitzgerald <mike@wyeast.net>]

James Clark wrote:
>I think a single comprehensive example in Section 2 would be useful.

Good.

>However, I think we also need to pay attention to the length of the spec.
>Although it's superficial, the number of pages in a spec does contribute to
>people's initial impression of its complexity.  Thus, I do think we should
>assume so basic level of understanding of XML, and XML Namespaces, and not
>attempt to incorporate a tutorial on these in the spec.

I can understand your concern about turning the spec into another tutorial.
I don't want you to do that either. I suggested block definitions as an
enhancement to aid understanding of a broader audience beyond the XML
cognoscenti, making the spec easy to grasp by someone who may be new to XML.
They will appreciate it. But I concede that the tutorial succeeds well for
this imagined broad audience already. Nonetheless, I believe block
definitions would only add about 1-2 pages to the spec's length. Not a dear
price to pay.

>I also want to give priority to adding examples where there is least one
>reader who in fact found it hard to understand without an example, and
>would have been assisted by an example.

I read: let's add an example if there is a reason to do so.