RE: Flow/Organization of Document

This message is in reply to issue #305 [1] that you raised during the XKMS
WG Last 
Call request on behalf of the XML Protocol WG.

The changes you proposed to the specification have been accepted and the
revised version of the specification may be seen at [2]

Issue a - added forward links to the sections that describe protocols
Issue b - Fixed - see para 36
issue c - Fixed - See Section 1.5, 4
issue d - Fixed - Section 2 is now protocol exchanges

At this point the work group believes all concerns raised in issue #301 have
been addressed and that the entire issue is closed, unless we hear
otherwise. (see [3] for additional resolutions)

The XKMS WG would like to thank you for reviewing and commenting on the
draft XKMS specification.

Regards, 
Phillip Hallam-Baker on behalf of the XKMS WG
VeriSign Inc.

> -----Original Message-----
> From: Joseph Reagle [mailto:reagle@w3.org]
> Sent: Monday, May 12, 2003 3:32 PM
> To: 'www-xkms@w3.org'
> Subject: 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 Wednesday, 6 August 2003 14:35:16 UTC