[Nmc-wg] Documents review (Michael)

[Jason Zurawski]

Hi Michael;

You appear to have some very strong opinions that affect large portions 
of the document.  I would encourage you to please make your notes in the 
SVN copies even as we discuss things on this list so that nothing is 
forgotten.  Comments inline.


> 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?)


I have added this comment for you.  Subscription may not be a regular 
message exchange right now but it is something that we must document as 
it does have implications for future services.  For example the IDC 
protocols (dynamic circuit related - something that Internet2's ION and 
AutoBAHN implement) have a subscription message that perfSONAR-PS 
services will eventually utilize and implement to gain information about 
aspects of the dynamic circuit networks.


> - Security considerations seem to be absent, like the transport layer
> that soap uses should provide integrity and privacy protection to avoid
> MITM-attacks etc.


I have added your name to the TODO list to fill out this section. 
Please research these topics and document the most important areas we 
should consider.  Security is very broad and not the focus of this work, 
but we can spend some space describing the risks and steps we can take 
to mitigate.


> - 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)


If you have noticed issues like these three in the document, please 
correct - language choice does not need to be a discussion point for 
everyone.  I did not make comments inside of the documents on these two 
points since I am sure you have a better idea where you have seen the 
problems.


> - On what standards do we build? NM, NML, others? 'perfsonar URNs'? We
> probably expect some pre-existing knowledge from our readers.


Pre-existing knowledge will come from references because we (and other 
groups) should not be re-inventing the wheel.  We will not be 
re-defining concepts like URNs (there are several GFDs that describe 
this as well as work that NML will publish 'real soon now') or topology 
descriptions (also something NML will be providing).

There will of course be caveats.  For example we don't implement 
namespaces exactly as GFD.84 recommended - so we note that we liked the 
standard and made some changes to better suit our needs.  I would expect 
there to be caveats surrounding the NML work as well (unless we want to 
gang up on Freek and force him to change things to fit our exact needs :))

In general, if there is a place that needs a further explanation or 
reference please note it as you are reading.


> - 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.


I have added your name to the TODO list and the introduction section to 
fill this in.


> - 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)


These are good comments, but since they are general I can't identify the 
specific areas you wish to alter.  Add some comments to the specific 
sections and subsections that need more focus or a correction in scope.

I do disagree with your synopsis of where to include schematic details. 
  I think everyone who has been with the perfSONAR project remembers 
that the schema files (and their associated comments) where not viewed 
as often as they should be.  For over 3 years there has been a call to 
document the details, at a higher level and separate from the RNC 
descriptions.  Comments in schema are the same as comments in source 
code - they give you a tiny piece of information that is worthless 
almost all of the time.  I agree that communication patterns are 
important, but message and protocol details are just as important.


> - 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.

I am going to address your last point first since it effects my answer 
to the previous two: the documents are not being split to allow for easy 
extension, they are split to eliminate repetitive language and concepts. 
  This work is one part of the entire 'spec', it represents the most 
basic and fundamental set of rules and interactions that are required 
for any 'real' exchanges. I would not call the contents of the base 
useful for anything other than reference - there will probably never be 
a service that speaks 'base' for example.

There will be an IS document to describe IS (topology/lookup) messages 
and I would expect there will be an AA document as well.  There is a 
work for MAs started and MPs and TSs will want to get in on the action 
evetually.  The strength of doing it in this manner is to save time by 
trying to not violate the DRY rule.  I do not think that this document 
can be viewed as an island and judged on what it does (or does not) 
contain without considering the remaining steps this working group was 
formed to do.  While I agree with your point that the focus should be on 
easily implementation/lookup of information in the end, consider that 
the entire spec is series.  I will reiterate that for this portion of 
the spec, rules should be a primary concern.

Thanks;

-jason