[nycbug-talk] Diagrams.

[Isaac Levy]

On Sep 10, 2011, at 2:59 PM, Jan Schaumann wrote:

> Isaac Levy <ike at blackskyresearch.net> wrote:
> 
>> (I recall years ago when I asked this on list someone shouted 'ASCII
>> art', [a perfectly acceptable answer]).
> 
> I'm gonna second that one.  Actually "drawing" ascii can be a bit of a
> pain, but that makes you actually think about the relationships and
> visuals a bit more.  And you can just check them in to your VCS and even
> plain diff them.

Agreed, I do think ASCII art is a powerful way to embed well-defined concepts diagrams in text, yet it has limits,

On Sep 10, 2011, at 6:40 PM, Jan Schaumann wrote:

> George Rosamond <george at ceetonetechnology.com> wrote:
> 
>> But ASCII art. . . LMAO.  That's fine for decent techs collaborating,  
>> but hardly presentable.  Although diffs add to the utility.
> 
> Hey, if it's good enough for RFCs...

Excellent example on page 1:
http://www.ietf.org/rfc/rfc768.txt

Epic [page 22]:
http://www.ietf.org/rfc/rfc793.txt

> 
> But yes, depends on the audience.

The process of using ASCII art is like carving something in stone.

I believe, beyond the audience, the choice to create ASCII art depends on the material.

ASCII art is physically limited to character size, etc... so embedding small, well defined ideas in a document or man page is really fantastic.

However, I can't see myself working with the following subjects as ASCII:

- Physical/Logical Network Topologies
- 'full-stack' Network/Web Application Interactions, e.g.:
  - (N) L7 load balancers talking to (N) app and (N) DB/Data services
- Digrams where photo imports of physical things (machines, or 
   whiteboards etc...) can be a critical way to communicate a design

These things take serious time to represent in ASCII, and are extremely difficult to maintain!
(oops, we need to add 1 more thing in the LH side there, we need to re-draw everything right of it!..) 

ASCII is not good for easily maintaining ongoing documentation for large/complicated/messy things.

> 
> Another perfectly reasonable solution I've found is to draw the diagram
> by hand on a piece of paper (if you like, even on a napkin) and scan it
> in.  Or whiteboard plus photo. :-)

Whiteboard + the camera-phone in everyone's pocket = Awesome.

Common newer cameras have resolutions completely capable of dealing with small details coming from the fat tip of a dry-erase marker.

My favorite time of the day is to spend time alone with a whiteboard, working out existing problems or new ideas- but they're not always presentable or 

> 
> Hmm, if you have the $$, interactive whiteboards like the SMART board
> (http://is.gd/77Wofl) are really cool.

Cool indeed, but I've spent more time with people in meetings getting the darned things to work, than focusing on the work...

> 
> None of these lend themselves to collaborative illustration, I'm afraid.
> But then again, I also like Dijkstra's quote:
> 
> "Every time someone draws a picture to explain a program, it is a sign
> that something is not understood."

Ha!  Point taken!  There's as much bad/useless info-porn in the world as there is bad/useless software.

However, he bulk of EWD's amazing life's work was written with a fountain pen on paper, he discouraged the use of computers in writing computer programs altogether.

There's a lot that EWD has written or said which blows my mind, but this quite absolute statement is not one of them- on so many levels.  Not every necessary program or idea can be well understood, even by a sole creator of a program.
Regarding diagrams: some people are visual communicators, some auditory, some react strongly to tactile inputs, etc.

"...you probably know that arrogance in computer science is measured in nano-Dijkstras."
Alan Kay, 1997 OOPSLA Keynote

Best,
.ike