Flow/Organization of Document

While the spec has improved a great deal, I've been hoping that folks new to 
the spec might be able to substantiate my lingering sense that the document 
doesn't flow as smoothly as it might. Since I'm familiar with the spec I 
don't completely trust my assessment but I was thinking:

a. Section 1 says there are two "service specifications" but doesn't say 
where they are more fully described or specified. Forward references?
b. The sections in section 1.7 do not correspond to the sections of the 
table of contents.
c. Section 1.5 has the same title as Section 4 (except that it has 
"specification"). How to make this flow better, or at least use the term (r 
not)  "specification" consistently.
d. Generally, I don't distinguish between a "message format" and a "message 
syntax." What do these section do differently?

I'm sure this is the result of our splitting/combinding documents, but we're 
to the point now where what we are doing is quite clear, and now we need to 
smooth out the flow. Consequently, I suspect we could improve the spec if 
we (1) kept in mind the progressive rendering of (description, example, 
specification), (2) had carefully considered section titles and (3) further 
nudged the reader along with "this section does blah blah blah, how blah 
blah blah is transported is in the following section foo foo foo"

Received on Monday, 12 May 2003 15:31:59 UTC