[Nmc-wg] Documents review (Michael)

[Michael Bischoff]

Hello all,

After reviewing the documents I, as I'm sure other people did, found a
couple of lesser important points that probably should be addressed. For
example the copyright notice 2008-2009 -> 2008-2010. As Jason has already
indicated that one should just send in the patches/commit to svn I will not
go over them here.

My more general points:

- Subscription isn't currently implemented as a fire and forget MEP(perhaps
we are not talking about the same subscription?)
- Security considerations seem to be absent, like the transport layer that
soap uses should provide integrity and privacy protection to avoid
MITM-attacks etc.
- Avoid "MUST" with fuzzy concepts. only use MUST for formal, well scoped,
unambiguous statements.
- Avoid unnecessary statements/(verbosity without added clarity)
Example:
"As described in Section 3, the communication protocol is simple and based
on the notion of Request and Response messages."

"As described in Section 3, the communication protocol is simple and based
on the notion of Request and Response messages."

"As described in Section 3, communication is based on the Request Response
MEP." (related to the point below:)
- Ensure clear separation between concepts by choosing carefully/utilising
the terminology used and be consistent
Example: (from MA document)
"The Measurement Archive protocol features three *messages* used to query
services identifying themselves as long or short term storage locations of
measurement data." ->Message types, message sets(as interfered from
definition) or Message exchanges(as interfered from description)
- On what standards do we build? NM, NML, others? 'perfsonar URNs'? We
probably expect some pre-existing knowledge from our readers.
- Add foundation/Convey intention(improve introduction?)
example: why do we have perfsonar(/nmc)? - not to 'sell it' but outline to
convey intent so that one can interpret the rest of the document better.
- focus more on stucture of cooperating parts and communication patterns and
tie the message content and/or structure to it.
avoid having just a bunch the gritty protocol details - an attached schema
in relaxng or xsd with inline comments can already convey this - put
differently I first need to figure out which kind of message I'm suppose to
start sending before I even care about how it's constructed.
- Scope, scope scope. *What* *can* and *what can't* I find in this
document/chapter?
- Focus on the widely used stuff first. Be critical of what you include now,
favor adding stuff in later versions if concepts haven't beeing fully
explorered / widely used.
(removing something later is hard)
- are we intentionally not touching upon AA and Lookup functionally in the
base document and if so why not? It feels really hard to grasp whats going
on without introducing it.

Overall I what I'm trying to stress is that the spec should be written as
such that it enables one to easily implement it as opposed to 'just'
documenting rules. Now this doesn't mean that it should be turned into a
manual, as that is actually counter productive as that would only add
verbosity where it could just as easy be placed in a separate document. What
I mean with easy to implement strive to enable easy lookup of specific
parts. (as that is how a spec is typically consumed)

On a related note:
While separating everything across documents so that it may be extended
easily seemed like a good idea to me as well when we initially started,
given how it is shaping up, I'm not sure that I still stand by it. As it
might well increase ambiguousness as it invites violating DRY also as time
increases having more then one document with more then one version might be
hard to consume.

Kind regards,
Michael Bischoff
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.ogf.org/pipermail/nmc-wg/attachments/20100128/8367f702/attachment.html