Subject: RE: Normative figures

From: "Gray, Eric" <[email-masked]>
Date: Mon, 9 Jan 2006 19:28:52 -0500

Stewart,

	See below...

--
Eric 

--> -----Original Message-----
--> From: Stewart Bryant [mailto:[email-masked]] 
--> Sent: Monday, January 09, 2006 6:50 PM
--> To: Gray, Eric
--> Cc: [email-masked]
--> Subject: Re: Normative figures
--> 
--> Eric
--> 
--> You are missing the point.
--> 

Out of politeness, let's consider the possibility that I am 
not missing the point.

-->
--> I was picking an example out of thin air, but it is the 
--> type of construct that we use all the time in fast-reroute.
-->

I follow that discussion in each WG in which it has come up.

--> 
--> The example was four routers connected together in a 
--> square with some randomly chosen asymetric costs. Such a 
--> network is trivial, but FRR need to cope with arbitary 
--> network fragments with arbitary costs, so there are lots 
--> of fragments that we have created for study the properties 
--> of.
-->

Yes.  And, if we're talking about wanting to make the figures
normative, I assume we are talking about a specification.  In
that case, it is far more important that the description MUST 
be precise, than it is that it MAY be convenient.

As I indicated in my response, it is possible to represent a
lot of different topologies in simplistic figures with textual
descriptions and - potentially other means of helping readers
to understand _and_ verify the specification.

--> 
--> One of the ways to operate on the fragment is to draw it and
--> then to figure out the packet flows, consequences of failure etc
--> etc.
--> 
--> Now the question is why should the examples in our drafts be forced
--> by our ability to describe them, rather than being the example that
--> most clearly illustrates the problem and its solution?
-->

There are two issues built into this question: 

1) Are the available tools preventing completion of the task, or
   do they merely constrain the ways in which it can be done?
2) Is the purpose of the task to describe, or to illustrate, the
   specified solution?

I believe these two questions - taken separately - have been 
beaten utterly to death.

In the first issue, it is clear that a number of people feel that
the current tools merely constrain the specification process.  To
many of those people, this is a good thing.  In addition, nobody 
has yet been able to demonstrate an example of a case where the 
tools - as they are (and including the potential for PDF use) are
preventing the completion of any specification task.

In the second issue, it SHOULD be clear that the task is to give
as precise a description as possible.  Most everyone agrees that
figures, tables and equations MAY help.  Most everyone agrees that
they MAY occasionally be necessary for correct understanding of a
specification.  And most people agree that text MUST be precise
and complete for specification wherever it is possible to do so.

Figures help to understand.  In many cases, they are not required.
The fact that an accurate description in text may not be easy to
produce is not nearly as important as the fact that a description
in text is easier to test for correctness.

We write specifications so that they are easier to read, validate 
and understand, not so that they are easier to write.

--> 
--> - Stewart
--> 
--> 
--> Gray, Eric wrote:
--> 
--> >Stewart,
--> >
--> >	You realize that the text "example" you gave is meaningless - 
--> >without making some (potentially non-obvious) assumptions, right? 
--> >
--> >--> -----Original Message-----
--> >--> From: [email-masked] [mailto:[email-masked]] 
--> >--> On Behalf Of Stewart Bryant
--> >--> Sent: Monday, January 09, 2006 2:47 PM
--> >--> To: Sam Hartman
--> >--> Cc: Harald Tveit Alvestrand; [email-masked]
--> >--> Subject: Re: Normative figures
--> >--> 
--> >--> Sam Hartman wrote:
--> >--> 
--> >--> >Hi.  With the exception of packet diagrams, I think all 
--> >--> the examples
--> >--> >you bring up benefit significantly from clear textual 
--> description.
--> >--> >
--> >--> Sam
--> >--> 
--> >--> I am not saying that clear text is not needed to accompany 
--> >--> a diagram.
--> >--> However a diagram allows a lot less text to be written 
--> producing a
--> >--> shorter clearer draft with less clutter.
--> >--> 
--> >--> For example you could say the following in text : 
--> router A connects to
--> >--> router B and D, the cost from A to B is 2, and the 
--> cost from A to D is
--> >4.
--> >
--> >	A --(2)--> B
--> >      |
--> >      +---(4)--> D
--> >
--> >--> Router B connects to router C. The cost to router A is 6, and
--> >--> the cost to router C is 10. 
--> >
--> >     + A <--(6)--+
--> >     | |         |
--> >     | +--(2)--> B --(10)--> C
--> >     |
--> >     +--(4)--> D
--> >
--> >(Assumes "cost" is from router B in both cases)
--> >
--> >--> Router C connects to router D. The cost to router B is 9
--> >--> and the cost to router D is 8. 
--> >
--> >     + A <--(6)--+
--> >     | |         |
--> >     | +--(2)--> B <--(9)---+
--> >     |           |          |
--> >     |           +--(10)--> C
--> >     |                      |
--> >     +--(4)--> D <----(8)---+
--> >
--> >(Assumes "cost" is from router C in both cases)
--> >
--> >--> The cost from router D to router A is 16 and ...
--> >
--> >  +------+
--> >  |      |
--> >  |  +-> A <--(6)--+
--> >  |  |   |         |
--> >  |  |   +--(2)--> B <--(9)---+
--> >  |  |             |          |
--> >  |  +--(16)----+  +--(10)--> C
--> >  |             |             |
--> >  +------(4)--> D <----(8)----+
--> >
--> >--> 
--> >--> ... the cost to router A is 99.
--> >
--> >?
--> >
--> >(Assuming you meant the cost from D to C - not A)
--> >
--> >  +------+
--> >  |      |
--> >  |  +-> A <--(6)--+
--> >  |  |   |         |
--> >  |  |   +--(2)--> B <--(9)---+
--> >  |  |             |          |
--> >  |  +--(16)----+  +--(10)--> C <-+
--> >  |             |             |   |
--> >  +------(4)--> D <----(8)----+   |
--> >                |                 |
--> >                +-----(99)--------+
--> >
--> >		(Figure foo?)
--> >
--> >
--> >-->
--> >--> In fact you would probably need a table to make sure that 
--> >--> you did not make a mistake. In either case it is hard for 
--> >--> most people to figure out the what the topology is much 
--> >--> less imagine packet actions.
--> >
--> >Actually, you need a figure to make sure that you did not
--> >make a mistake, and a second set of eyes to compare what 
--> >you said to what you apparently meant.
--> >
--> >--> 
--> >--> Now compare this to:
--> >--> 
--> >--> "The network and costs are as shown in figure foo."
--> >--> 
--> >
--> >Is the above actually figure foo?
--> >
--> >The reality is that it would be better to break it this way:
--> >
--> >"In the network in figure foo, the link costs are as follows:
--> >
--> >    A -> B =  2
--> >    B -> A =  6             +-> A <----> B <-+
--> >    A -> D =  4             |                |
--> >    D -> A = 16             +-> D <----> C <-+
--> >    B -> C = 10
--> >    C -> B =  9                 Figure foo
--> >    C -> D =  8
--> >    D -> C = 99                                          "
--> >
--> >--> Simple text and the visualisation is already done for you
--> >--> so you can focus on the problem.
--> >-->
--> >
--> >The reality is that putting things entirely in pictures means
--> >that less validation of the intent of the picture is possible.
--> >Keeping pictures as simple as possible is, therefore, a goal
--> >since it is far easier to make mistakes in complex figures and 
--> >far more difficult to determine that a mistake has been made.
--> >
--> >Using a mixture of text and figure(s), tables or - possibly -
--> >equations makes it both more understandable and easier to be
--> >certain of conveying the idea(s).
--> >
--> >For example, in the above, I could verify that I understand 
--> >your intent by asking:
--> >
--> >"From this it is apparent that the link cost (D->C) is 99, 
--> > but the actual minimum cost of getting from D to C given by 
--> > the formula:
--> >
--> > (D->A) + (A->B) + (B->C) = 16 + 2 + 10 = 28
--> >
--> > Is that correct?"
--> >
--> >If we choose to use a simple combination of representations,
--> >rather than strictly expecting a figure to explain it all,
--> >the figure is likely to be far simpler.  For example, using
--> >an approach similar to the above, you could probably describe
--> >a much more complex network than 13, or 20 or maybe even 30
--> >nodes using ASCII art.  The purpose of the picture is to be
--> >a simplified referent.
--> >
--> >--> 
--> >--> Now I realise the above could be done in ascii art, but we 
--> >--> have problems that need 13 or more nodes to set up.
--> >--> 
--> >--> >  I believe I'd think that even if I could see the diagrams 
--> >--> >  and I believe I have enough experience with visualization 
--> >--> >  (although not sight) to be confident in that belief.
--> >--> >
--> >--> >  
--> >--> >
--> >--> >As such, I don't believe these diagrams should be normative.
--> >--> >
--> >--> >
--> >--> >I actually thin that many of the tunnel overlay 
--> network documents
--> >--> >(PWE3, L2VPN, L3VPN) could benefit significantly from 
--> more focus on
--> >--> >the text of the descriptions of situations being described.
--> >--> >  
--> >--> >
--> >--> It is probably a question of how we work and the tools that we
--> >--> find most effective.
--> >--> 
--> >--> >If you believe that normative documents are required, I'd 
--> >--> like you to
--> >--> >explain why the diagrams cannot be described in the text, 
--> >--> why doing so
--> >--> >would decrease the quality of the specification, or why 
--> >--> doing so would
--> >--> >not be a useful investment in our time.
--> >--> >
--> >--> >
--> >--> >  
--> >--> >
--> >--> One reason is that it takes a lot of text to describe what 
--> >--> can be drawn
--> >--> with a few lines and symbols. Many people will get lost in 
--> >--> the text and
--> >--> in any case would have to transcribe the text into a 
--> diagram for
--> >--> themselves before they could understand what is happening.
--> >--> 
--> >--> - Stewart
--> >--> 
--> >--> 
--> >--> 
--> >--> 
--> >--> 
--> >--> _______________________________________________
--> >--> Ietf mailing list
--> >--> [email-masked]
--> >--> https://www1.ietf.org/mailman/listinfo/ietf
--> >--> 
--> >
--> >
--> >  
--> >
--> 

_______________________________________________
Ietf mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/ietf

---

From: Stewart Bryant <[email-masked]>
Date: Tue, 10 Jan 2006 04:40:18 +0000

Eric

We write specs so that they will be correctly implemented.
Anything that makes a specification easier to correctly understand
surely makes it more likely that it will be correctly implemented?

The cost of incorrect implementation is so high that we can
can afford to pay a relatively high cost in the effort and
technology needed to read and write the specification.

- Stewart

---

From: Stewart Bryant <[email-masked]>
Date: Tue, 10 Jan 2006 05:00:49 +0000

>be precise, than it is that it MAY be convenient.
Please can we clarify the existing rules:

For a standards track document is it technically acceptable to provide:

A .pdf that is complete (but is non-normative under current rules)

plus

An ASCII text in which the background material refers to figures in the
.pdf  but which contains the essential normative statements.

i.e. Is a standards track RFC approvable when it is correct in the 
technical
sense, even if it is almost incomprehensible without the text, figures and
equations from its non-normative twin.

- Stewart

---

From: grenville armitage <[email-masked]>
Date: Tue, 10 Jan 2006 17:51:47 +1100

Stewart Bryant wrote:

> 
>> We write specifications so that they are easier to read, validate and 
>> understand, not so that they are easier to write.

> surely makes it more likely that it will be correctly implemented?

I'm a little confused. What is it about Eric's formulation of the statement
that you take exception to in your followup question? They sound the same
to me. (Or is it that you believe "easier to write" necessarily leads to
"will be more likely to be correctly implemented", and therefore "easier
to write" should not be excluded as a desirable goal of our specification
writing process?)

cheers,
gja