[rfc-i] Now tell me how to communicate this as effectively in plaintext

Larry Masinter masinter at adobe.com
Tue Apr 24 11:09:13 PDT 2012

Hi Philip,

Thank you for your document.

I'm not just as an idle observer, I signed up to prepare an overview of the 
topic in your document. https://www.w3.org/2001/tag/group/track/actions/697.
If you'd like to talk about the document content itself, perhaps we could
talk offline; I'm sending comments to rfc-interest because you brought it
up as an example of effective diagramming.

> I have been working on the attached document for several months. 

I respect that you've worked on it a long time.

>   It
> describes a proposal to change the structure of PKI.

It describes many things, including a model of the current systems
deployed, a set of threat models, speculation on the political climate
in China, analysis of alternative proposals. It's hard to sort out
what you're talking about in most situations, and the diagrams
don't help.  Perhaps if you'd spent more time organizing the paper
and less drawing diagrams the results would have been clearer.

>  Note that none of
> the other proposals referenced are described in RFC form either, nor
> do the authors have any intention of using that format.

But http://tools.ietf.org/wg/dane/draft-ietf-dane-protocol/ is
in RFC form.

> The subject matter is neither simple nor straightforward. 

I agree that the subject matter seems complex, but the document
could be simplified significantly if the topics were simplified. The 
diagrams don't help, partly because to understand them, you have
to understand the captions and terms within, which are difficult
to follow.

> The arguments are not straightforward either. PKI is a complicated subject
> because it deals with the real world and the real world is complex.

Science of the artificial: the best systems we design to solve real world
problems can be described simply.

> While all the diagrams and illustrations are described in the text, it
> is much more likely that people will understand the diagrams than the
> text.

I think the text is unnecessarily complex. I didn't find the diagrams
particularly helpful, your use of pictures of computers and arrows
more confusing, as I couldn't tell the significance of colors, lines,
arrows, or placement. You may imagine you're communicating more
with the diagram than you are, because you're associating more
semantics to the icons chosen and the layout of the diagram than
is actually there. Understanding a diagram requires swapping in
an entire new visual vocabulary.

> Now while I could convert this into plaintext format I am not going
> to. I am going to make my argument in the format I think is going to
> be most effective for communication.

Many people use powerpoint with pictures to explain their
arguments.   RFCs are not, for the most part, the best way to
communicate arguments and comparisons of technology.

I'm sorry if I disagree that you've made your argument in the
format (speaking broadly) that is _most_ effective for communication.

> 1) Does anyone seriously want to argue that the document would be
> easier to interpret in plaintext format without any diagrams?

This is a strawman.   

The  diagrams didn't help me interpret the document. 
There would be many other markup techniques I think would be
_more_ effective in making your arguments clearer -- 
 e.g., hyperlinks to the definitions of terms used with technical
> 2) Do people respect the fact that it would take me a great deal of
> time to write text that could come anywhere near as clear as the
> diagram?

With respect, I think it's worth taking the time to write clearer text.
I'm willing to help.

> 3) Does anyone imagine people would read the result?

Yes, more people would read clearer, shorter, and more well-organized

> 4) Would anyone insist on plaintext if they thought that people had a
> choice in the standards organization they participate in?

People choose standards groups for many reasons more important 
than the document format, so this is irrelevant.

> [I understand that the attached file will not work on kindle but I
> would be only too pleased to produce the file in an alternative format
> if we agreed one. Indeed the kindle format might well serve the
> purpose]

I think this is irrelevant. The problem with the document isn't the format.
Perhaps there are diagrams that would be useful to explain your
proposal and compare it to alternatives. A table of requirements
and an evaluation of proposals against requirements would help,
for example. 

Note that I'm not arguing for ASCII text, I'm just arguing that
It's hard to produce diagrams that are actually as helpful to the
reader as they are to the creator.


More information about the rfc-interest mailing list