Subject: [MMUSIC] ICE outline

From: "Rohan Mahy" <[email-masked]>
Date: Wed, 3 May 2006 17:14:04 -0700

Hi,

The sections in ICE are quite varied in length and some of the section
titles are not really well scoped.  I think a lot of this could be solved by
reorganizing some of the sections.  I read through this and I have a
proposed reorganization.  Other than the two sections in asterisks and some
text in section 7.3 that has nothing to do with encoding SDP, I don't think
this proposed outline would require anything but moving the sections
around.  I did a quick read for flow and to make sure there are not a lot of
forward references and I think this looks reasonable.

What do folks think of this?

thanks,
-rohan

old    new
1    1.  Introduction
2    2.  Terminology
3    3.  Overview
-    4.  Interaction with SIP
4    4.1 Sending offers
5    4.2 Answer generation
6    4.3 Processing answers
7.11    4.4 Subsequent offers/answers
8    4.5 Reducing delay
9    4.6 Forking
10    4.7 Preconditions
-    5   ICE procedures - generating SDP
7.1    5.1 Gathering addresses
7.2    5.2 Prioritizing candidates
7.2    5.3 * Selecting The Active Candidate *
7.3    5.4 Encode in SDP
-    6.  ICE Procedures - connectivity checks
7.4    6.1 Form candidate pairs
7.5    6.2 Ordering candidate pairs
7.6    6.3 ** The Candidate Pair State Machine **
7.7    6.4 Sending binding requests
7.8    6.5 Receiving binding responses
7.9    6.6 Promoting a candidate to active
7.10    7.  Processing peer derived candidates
-    8.  Media processing
7.12    8.1 Sending keepalives
7.13    8.2 Sending media
7.14    8.3 Receiving media
12    9.  Grammar
11    10. Examples
13    11. Security
14    12. IANA
15    13. IAB
16    14. Acknowledgments
17    15. References

* optionally split the current section 7.2 into two sections.
** several sections actually discuss connectivity checks, so the current
section head for 7.6 is mis-scoped.  This section really covers the state
machine for each transport address pair.
_______________________________________________
mmusic mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/mmusic

---

From: Philip Matthews <[email-masked]>
Date: Thu, 4 May 2006 11:14:23 -0400

Hi Rohan:

A few comments on your proposal.

I like the idea of bringing together all the sections that deal with  
the interaction
with SIP. I don't care if this goes before or after the main  
description sections.

I don't really care if the main ICE procedures are all subsections on  
one big
section (as they are today) or subsections of three smaller sections
(as in your proposal).

Some other changes I would like to see:

Personally, I think the document would be more readable the first  
time through
if all the informative material went before the Terminology section,
and all the Normative material went afterwards.
As I see it, all the material in sections 1, 3, 4, 5, and 6 are  
Informative,
and all the other sections are Normative.
So I suggest moving the current sections 3, 4, 5, and 6 to before  
section 2
(perhaps included the former sections as subsections of section 1).
At the same time, all the terms in the Terminology section could be  
introduced
in a narrative way in the Informative part of the document,
with explanations and perhaps a diagram.

The problem today is that a first-time reader almost immediately  
encounters
the Terminology section which is totally opaque if you are not  
already familiar
with the definitions introduced.  My co-worker said he just skipped  
that section
entirely because he could not make heads or tail of it.

The other change I would like to see is an integrated description of  
the processing
of a STUN request and STUN reply. Right now, the reader has to try to  
meld together
three very different descriptions:
- The entire draft-ietf-behave-rfc3489bis, which describes the base  
STUN procedures
- The current sections 7.7 and 7.8 describing processing for ordinary  
candidates,
    which modifies the handling in 3489bis
- The current sections 7.10, 7.10.1, and 7.10.2, describing the  
processing for
    peer-reflexive candidates, which modifies all the above
I found it very difficult to figure out in my head what the result of  
this three-way merge is.

- Philip

On 3-May-06, at 20:14 , Rohan Mahy wrote:

> Hi,
>
> The sections in ICE are quite varied in length and some of the  
> section titles are not really well scoped.  I think a lot of this  
> could be solved by reorganizing some of the sections.  I read  
> through this and I have a proposed reorganization.  Other than the  
> two sections in asterisks and some text in section 7.3 that has  
> nothing to do with encoding SDP, I don't think this proposed  
> outline would require anything but moving the sections around.  I  
> did a quick read for flow and to make sure there are not a lot of  
> ** several sections actually discuss connectivity checks, so the  
> current section head for 7.6 is mis-scoped.  This section really  
> covers the state machine for each transport address pair.