RE: Effort to simplifying our spec

Attached are my investigations as well.  I added "click to expand" for
the XML representations (not the mappings) for the first half dozen
components.  Try it out!

My feeling is that this approach raises a lot of questions.  If we
collapse the spec by default, someone who prints the spec might be in
trouble.  Searching and linking to a hidden section is also likewise
complemented.  If we expand by default, the initial reader of the spec
isn't actually helped.  A reader that is investigating, and then
searching, will want a global "collapse all" and "expand all".  These
controls would be most useful if they were sprinkled throughout the spec
(like any place that is collapsed).  All in all, seems like a slippery
road to defining an application - which is much more complicated than a
document.

I don't think the approach represented here is substantially better than
linking to a section containing all the infoset and mapping stuff, if we
even decide to do that.

> -----Original Message-----
> From: David Booth [mailto:dbooth@w3.org]
> Sent: Wednesday, March 17, 2004 2:21 PM
> To: David Orchard; Jonathan Marsh
> Cc: www-ws-desc@w3.org
> Subject: Effort to simplifying our spec
> 
> DaveO & Jonathan,
> 
> SUMMARY
> I don't think the style sheet approach will work.  I recommend we
continue
> as is.
> 
> EXPLANATION
> I've looked over our Part1 spec to think about how we might simplify
the
> presentation to the reader.
> 
> At present, I don't think a style sheet approach that would expand or
> contract the text is feasible.  The main issue is that each section
has
> both a subsection on the properties of that component, and a
subsection on
> the mapping from the XML infoset to those properties.  For example:
>
http://dev.w3.org/cvsweb/~checkout~/2002/ws/desc/wsdl20/wsdl20.html#Defi
ni
> tions_XMLRep
> and
>
http://dev.w3.org/cvsweb/~checkout~/2002/ws/desc/wsdl20/wsdl20.html#Defi
ni
> tions_Mapping
> 
> Much of the content of those subsections is fairly boilerplate, merely
> repeating what is evident from the pseudo-schema above.  But the
problem
> is
> that they aren't ENTIRELY boilerplate: both of these subsections have
> meaningful, non-boilerplate text mixed in with (boring) boilerplate
text.
> 
> It might be possible to factor out the meaningful, non-boilerplate
text,
> but I'm not sure we could reliably ensure that no meaningful text ever
> crept back in, so I'd be wary of using a style sheet to hide parts.
> 
> I don't see an easy solution to this problem, so at this point I
suggest
> we
> continue as is.
> 
> 
> --
> David Booth
> W3C Fellow / Hewlett-Packard
> Telephone: +1.617.253.1273