Re: [ws-caf] comments on the demo documents

[Kevin Conner <Kevin.Conner@arjuna.com>]

Mark Little wrote:
> Here are a few comments on the demo documents Kevin sent round at the 
> start of August.

Thanks Mark.

> WS-Context demo document:
> 
> In the overview, I'd change "WS-CAF context" to "WS-Context context" and 
> include a reference.

Text changed.

> Can you also turn consecutive line numbering on? Currently the line 
> numbers get reset at the start of each major section.

Done.

> It would be good to call out explicitly at the start which optional 
> aspects of WS-Context the demo uses and which is doesn't (maybe section 
> 5, since it touches on a few of these things) . Although mandatory items 
> can be assumed to be implemented (they're mandatory after all), 
> something clear and concise about the optional functionality would help.

I'll add a section to both documents to cover this.

> In section 6, change "Retailer Service provides" to "Retailer Service 
> provider"?

Oops, typo :-)

> I'd suggest using the same terminology and style as the WS-CAF 
> specifications where possible. So, /must/ would be MUST, for example. 
> Also, bold schema use within the text and make sure it's clear which 
> namespace. For example, *wsctx:foo*

Done.  This came straight from the OASIS template document though.

> Have you and the group considered adding some normative scenario 
> interactions, so that implementers can more easily test for 
> interoperability and compliance?

I have considered this outside the context of the demo.  I feel it would be very beneficial, especially as we progress up the stack, to include interoperability scenarios that can be automatically tested.

The demo does provide a degree of confidence in the interoperability of the participating implementations but, IMHO, falls short of an interoperability test.

> WS-CF demo document (I'll ignore similar comments to WS-Context demo 
> document):
> 
> In the abstract, I'd just talk about WS-Coordination Framework contexts 
> and not WS-CAF Coordination Framework contexts. It should be clear to 
> readers that WS-CF (and WS-Context) are part of the WS-CAF TC. There'll 
> never be a WS-CAF specification.

Done

> Is the intention that this document should stand entirely on its own? If 
> so, then section 3 makes sense. If not, then we may be able to trim some 
> stuff here and simply reference the WS-Context demo document.

The original intention was for it to stand on its own.  I don't mind either way :-)

> Either way, it would be good to have a section at the start on what the 
> differences are in the architecture/requirements/etc between the two 
> demos. For example, how is coordination being used and what's the protocol?

The document does mention how the coordination framework is used and the protocol is demo specific.  It's not as concise as it perhaps should be though :-)

I will add a section to explicitly cover this.

> BTW, my preference would be to reference the previous document and keep 
> this one as simple as possible.

> The text in section 6 seems incomplete. No chapter numbers for example.

Not sure how this happened, they do show up in the document.  I'll double check the next time I generate a PDF.

	Kev

-- 
Kevin Conner
Arjuna Technologies Ltd.