[Bug 5152] tableau presentation difficult to understand

http://www.w3.org/Bugs/Public/show_bug.cgi?id=5152

           Summary: tableau presentation difficult to understand
           Product: XML Schema
           Version: 1.1 only
          Platform: PC
        OS/Version: Windows XP
            Status: NEW
          Severity: normal
          Priority: P2
         Component: Structures: XSD Part 1
        AssignedTo: cmsmcq@w3.org
        ReportedBy: johnarwe@us.ibm.com
         QAContact: www-xml-schema-comments@w3.org


3.2.2 XML Rep of Attribute Declaration Schema Components is the first context
in which the tableau format is really being pushed as far as it can go while
still being at all comprehensible, and it's not the worst.  I am suggesting as
small a set of changes as I can that I think will really improve readability.

- move the paragraph (or even just its first sentence) that enumerates the
cases covered in the tableau from after it to before it ("Attribute
declarations can appear at the top level of a schema document, or within
complex type definitions")

- replicate the logic embedded between the tableau's divisions ("otherwise if
the <attribute> element information item has <complexType> or <attributeGroup>
as an ancestor...") as text before the tableau so the reader gets an overview
before diving into the bits

- add a sample in 1.5 where the tableau format is introduced showing this type
of "code interspersed with nested tables"

- add a reference to "attribute use" (or any other distantly defined entity
when it is first used if it has not yet been introduced in the beginning to end
flow), e.g. in "otherwise if the <attribute> element information item has
<complexType> or <attributeGroup> as an ancestor..."

If larger scale changes are possible, I would reorganize it further so that in
place of each single tableau (one dealing with all cases) is a series of them
(one per case).  The beginning of the section would aggregate just the current
logic, what you currently have as separators between sections, and point to a
specific heading with the tableau for each leaf case, containing the
(restricted to this case) XML and all the downstream properties.  The property
descriptions would come between the logic/list of cases and the first leaf
case's details.

Received on Monday, 8 October 2007 18:25:31 UTC