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