bryan rasmussen wrote:
> I think for documentation you will almost often come outside the
> documenting facilities of a schema language, or the usage made of it.
> Also because there are various styles of documentation. The
> documentation structure that is most often used for XML mirrors the
> hierarchical nature of the format, I don't actually think I've ever
> found that useful. Documentation probably is better if it is a
> document, with some sort of introduction, a look at the overall logic
> of the language somewhere at the top.
>
> The hierarchy of elements is the least interesting part of the documentation.
>
> Cheers,
> Bryan rasmussen
>   
Yes, and indeed the potential need for multiple use cases and multiple 
views of the document based on those use cases may be better served by 
multiple schemas and transformations. 

If the idea is to be user-centric about the documentation, then a fair 
place to start is by making sure the system is user-friendly.  So often 
it turns out that a company's internal formats are different from its 
external formats, and that the data in the external format only has the 
detailed semantics of the internal format.

In the LIXI standard here in Australia, they worked out a system where 
instead of documenting the elements, they provide the ability to view 
each stakeholder's individual take on the semantics of the elements. 
That way each stakeholder describes the data according to their 
vocabularies, and people who want to interchange can review whether in 
fact each other's data and assumptions is good enough.

Cheers
Rick Jelliffe