Subject: [P2PSIP] Editorial Comments on draft-bryan-p2psip-reload-03

From: Alan Johnston <[email-masked]>
Date: Tue, 11 Mar 2008 16:10:23 -0500

Organizationally, this document is not in very good shape.   I 
understand it has been a work in progress, but it is also an -03 version 
with experienced co-authors which should be a whole lot better for the 
working group to make an informed decision on.

I can not provide comments on individual sections or pages because most 
comments are global in scope.  I believe this document desperately needs 
an assigned editor from the outside with experience editing large IETF 
specs over a long period of time and a co-editor picked from among the 
current co-authors.   They would need to rewrite approximately 60% of 
the text.  Also, I think a structured rewrite will uncover lots of 
missing normative text and specification.  Here are some specific issues:

1. No normative/non-normative separation.

Effectively, the entire document consists of normative text.  The first 
normative language is on page 19.  Normative text is often buried in 
long paragraphs of exposition and explanation.  Some of the explanatory 
text is repeated multiple times in multiple locations.

2. Needs better organization.

The early parts of the document contain extremely detailed sections on 
certificate usage and signature generation before the reader even 
understands what is being protected and signed.  Also, there is lots of 
text about the Enrollment server, which is actually out of scope.  I'd 
recommend moving most of this text to Appendices.

3. No introductory explanations.

The document needs an Introduction with a non-normative explanation of 
how the protocol works.  As it stands, the reader has to wait until 
around page 76 to begin to get an understanding how the protocol 
works.   Usually, documents have the other problem - too much 
introduction and not enough normative statements.  This document seems 
to focus on minute details and leaves the big picture underspecified.

4. Not even one call flow.

The sequence of PING/CONNECT/JOIN/UPDATE/STORE used to join the overlay 
is far from obvious and needs at least one non-normative call flow to 
help the poor reader understand.  Bootstrapping is also tricky to 
understand without at least one call flow. 

Thanks,
Alan

_______________________________________________
P2PSIP mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/p2psip