Subject: RE: Diagrams (Was RFCs should be distributed in XML)

From: "Gray, Eric" <[email-masked]>
Date: Wed, 16 Nov 2005 15:40:40 -0200

Stewart,

	While an interesting turn of phrase, "hair shirt approach"
is hardly an accurate analogy, nor is it particularly apt to compare
presentation materials (where there's a real live person in front
of you to answer questions) with specifications (where there usually
is not).

	One dilemma associated with unlimited scope for complex drawing 
is the fact that group-thinking rarely ever results in simplification
(for pictures in particular, especially when those pictures are meant 
to be normative).  While an author, editor or working group may want
to keep figures/pictures simple, what are the criteria we should use
to determine when an appropriate level of complexity is achieved?

	I would argue that those criteria would be along the lines of
what I suggested earlier - irrespective of the editing technology we
might use.  And that would go along with the notion of using the 
simplest common document format sufficient for the task.

--
Eric

--> -----Original Message-----
--> From: Stewart Bryant [mailto:[email-masked]] 
--> Sent: Wednesday, November 16, 2005 7:30 AM
--> To: Lars-Erik Jonsson (LU/EAB)
--> Cc: Gray, Eric; [email-masked]
--> Subject: Re: Diagrams (Was RFCs should be distributed in XML)
--> 
--> It's interesting that when authors turn up at IETF to 
--> explain their work/resolve issues etc they use colored 
--> diagrams to do so - not ASCII art.
--> 
--> Some of this is fashionable, but in many cases it is to 
--> clearly articulate a point in the very little time made available.
--> I don't see why such powerful techniques shouldn't be 
--> applied to the specifications themselves to allow the 
--> reader to most grasp what is being said with the minimum effort.
--> 
--> I am afraid that I don't subscribe to the hair shirt 
--> approach to drawings. I think that they should be exactly 
--> fit for purpose neither too complex, nor too simple, and 
--> that the need to work round the limits of 72 ASCII 
--> characters should not be a constraint that limits the 
--> clarity of expression.
--> 
--> For example look at slides 5 and 6 in
--> http://www3.ietf.org/proceedings/05nov/slides/pwe3-2.ppt
--> 
--> and compare to figure1 in
--> http://www.ietf.org/internet-drafts/draft-balus-bocci-martin
i-dyn-ms-pwe3-00.txt
--> 
--> The latter shows the components of the system, but it is 
--> impossible to put the detail shown in the slides into the 
--> diagrams in the specification itself with our current tools.
--> 
--> Look at the figures in
--> http://www.ietf.org/internet-drafts/draft-bocci-bryant-pwe3-
--> ms-pw-arch-01.txt
--> particularly figure 8. We are at the limit of what we can 
--> describe in these diagrams.
--> 
--> I can also find examples in the IP Fast Re-route work where 
--> we struggle to show network snippets in ASCII with the 
--> associated addressing and subsequent tunneling, and yet the 
--> operation is simple to show in ppt, pdf, etc etc, 
--> particularly with colour.
--> 
--> Another example - many of the ideas that we talk about in 
--> the IETF start life as a few coloured lines on a large 
--> whiteboard - because that is the simplest way to visualise 
--> these ideas and to express them for the first time to our 
--> peers. That style of expression therefore seems to the 
--> specifications themselves and for exactly the same reason - clarity.
--> 
--> Perhaps it is because the work that I do is mainly on 
--> overlay network techniques where it is necessary to 
--> describe how the virtual network maps onto the physical 
--> network that I find difficulty producing clear ASCII art, 
--> but I would be surprised if I were alone in that view.
--> 
--> If we think that ASCII art is all that is needed, perhaps - 
--> as an experiment - we should forbid the use of anything 
--> other than ASCII art in presentations at the next IETF?
--> 
--> - Stewart
--> 
--> 

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

---

From: Stewart Bryant <[email-masked]>
Date: Thu, 17 Nov 2005 10:01:04 +0000

>of you to answer questions) with specifications (where there usually
Indeed - where there is a person, the audience can ask questions of
clarification, but an document must stand by itself. Clarity is
therefore more important in a document, and we should therefore
use the best tools available.

>to determine when an appropriate level of complexity is achieved?
Occam's razor seems to be the best criteria for such a dilemma.

Using a primitive presentation mechanism as a substitute for
peer review on the appropriateness of the solution seems something
of a cop-out that harms our ability to produce the most appropriate
solution described in the clearest possible way.

>simplest common document format sufficient for the task.
I don't much care what technology we use, that is not a key issue for
me. The key issue is to be able to describe a protocol using the
most appropriate mixture of clear English, clear diagrams and if
necessary pseudo-code. We can do the first and the last but seem
reluctant to recognize the need for the middle.

- Stewart