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

From: "Lars-Erik Jonsson (LU/EAB)" <[email-masked]>
Date: Tue, 15 Nov 2005 15:18:55 +0100

Very well stated!!!

The ASCII-requirement is (apart from being a compact, generic, free,
non-complex, document format) indirectly forcing people to really
make diagrams simple, i.e. not put too much crap (complexity) in one
single figure.

After having had to read documents from other organisations people
often cite as "SDO's", I am personally convinced that the good sides
of using ASCII completely outweights the potential negative aspects.

/L-E

> Stewart,
> 
> 	I suspect most people prefer reading documents that contain
> diagrams, but anything that limits the complexity of a diagram -
> especially for documents most often read on a computer screen - is
> a feature, rather than a bug.
> 
> 	If a diagram is included to communicate (rather than obscure) 
> an idea, then readers should be able to correlate descriptive text 
> to the diagram - either because the diagram is simple enough that
> it is not necessary to keep referring to it, or because the entire
> description can be viewed while looking at the diagram.
> 
> 	Sometimes language limitations are a good thing, when they
> are tied to specific ways of presenting information.
> 
> --
> Eric

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

---

From: Stewart Bryant <[email-masked]>
Date: Wed, 16 Nov 2005 12:29:40 +0000

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-martini-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

---

From: Masataka Ohta <[email-masked]>
Date: Wed, 16 Nov 2005 23:02:21 +0900

> to most grasp what is being said with the minimum effort.

It merely promote complex protocols to disallow the reader to
grasp even with the maximum effort.

> a constraint that limits the clarity of expression.

It's good that protocols needing more than 72 ASCII characters
are forbidden.

For examples, see NGN diagrams.

For further improvement to forbid the work round, it is good if
RFCs more than 20 pages long are disallowed.

						Masataka Ohta

---

From: Stewart Bryant <[email-masked]>
Date: Wed, 16 Nov 2005 14:44:43 +0000

>grasp even with the maximum effort.
Limiting the documentation mechanism is not an appropriate way to
limit the complexity of protocols. That is the function of
the WG/IETF/IESG review process.

>For examples, see NGN diagrams.

They are not forbidden - they are just harder to describe and are hence
more likely to have bugs that no one notices until we have a problem.

>RFCs more than 20 pages long are disallowed.
Which results in protocol definitions that are choped up into so
many parts that no one can see how to put then back together.

- Stewart

---

From: Masataka Ohta <[email-masked]>
Date: Thu, 17 Nov 2005 00:58:28 +0900

> many parts that no one can see how to put then back together.

That's fine.

						Masataka Ohta

---

From: Marshall Eubanks <[email-masked]>
Date: Wed, 16 Nov 2005 11:00:22 -0500

Hello;

I suspect that there is a lot more reliance of non-ASCII art out  
there than
is officially admitted.

I do not know how, for example, you can  understand the PIMv2 state  
machine without reference to the (non-ASCII) diagrams provided in the  
(non-ASCII) version of the draft.

Regards
Marshall Eubanks

---

From: Ted Faber <[email-masked]>
Date: Wed, 16 Nov 2005 09:38:43 -0800

> ASCII art in presentations at the next IETF?

Seconded.

All in favor?

-- 
Ted Faber
http://www.isi.edu/~faber           PGP: http://www.isi.edu/~faber/pubkeys.asc
Unexpected attachment on this mail? See http://www.isi.edu/~faber/FAQ.html#SIG
_______________________________________________
Ietf mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/ietf

---

From: Bob Braden <[email-masked]>
Date: Wed, 16 Nov 2005 10:33:40 -0800

>(non-ASCII) version of the draft.

Some might wonder whether it is possible to understand the PIMv2
state machine under ANY circumstances.

Bob Braden