pleased-looking squid with butter

Software is a collection of complicated ideas embodied as machine code. Pictures are an excellent way of conveying complicated ideas. Obviously we should be documenting software source code with pictures...right? Yet despite decades' worth of attempts at developing visual programming languages, typing plain old text into plain old text files continues to be the most effective way of implementing and documenting software.

As a compromise, you can embed ASCII art into source code comments or README files. This isn't a bad solution, and there are several desktop and web-based tools (e.g. Emacs artist-mode) which let you draw simple vector objects--boxes and lines--then render the drawing as ASCII. But when you try to update the ASCII art, you quickly run into the limitations of these tools. Rendering vector objects into ASCII effaces the information associated with the vector objects: you can no longer move or reshape the vector objects because it's just a collection of ASCII characters.

Scribble is an ASCII art editor which lets you draw vector diagrams and render them into ASCII art. The original vector objects are converted into a short (well, short-ish) URL and string, appended to the bottom of the diagram. Paste both the ASCII art and URL into your source code or README file. If you need to modify the ASCII art later, you can regenerate the original vector shapes in Scribble by using the URL.

I wrote Scribble to generate ASCII art for inclusion in my own source code and README files. 

                                +-+
                                |v|
                                |v| fifo
                                |v|
                                +-+
                                 |
                                 | reference
                                 |
                                 |
                                 v
                         <-_ +-------+
                            "|channel|
                             |model  |
                             +-------+
                                 |    "-_update chan model
                             y^  |       ""__
                                 |           "-
                                 v            |
      +---------+  input x      +-+           |     +---------+
      |>>>>>>>>>| ------------->|+|---------------->|>>>>>>>>>|
      +---------+               +-+       residual  +---------+
         fifo                                          fifo


http://buttersquid.ink/?spore=bNobwRALmBcYDYEsB2BTAzig5mANGAHgIwwDMhe+ATDIQ
Bx4Cex0lADI9S+2CgIY14UAIxjc4Ae3wwAtAFY8EhjPLwosZAAcArhAAEUhRABuMCACctKAL45w
ayEMm4CpSoxoBOPBHz2A1M4m0OaWNnYw8MjoWM5EpPIEnLIqTDBsHGncfKKCItAqElLQ0gXiSvm
GEWboCAAmWrxwznDGphbWtpARiKgY2BTMJCQUnEOMzIQJDJx0gvzQWXmlRdIALAplOaoRDAB6za
3B7WFdsD3R-QTMqwBsIzC34zQA7Bn5Xjzzi1uFMh+KP3saF0AF5dBg9BAUL4ADpIOCg3QQcSYTB
wFC6IwINAIISICBKQxBABmjQwJ3s5z6sWYlASVAedzAqXyKRmr0+Ah4eTETmgTIBFW2sC0GlqvC
hugAxgALXhIXQAW3EtRQTSJbVCnXsEEcBhcLA+5UIKh89ll8tQcDhytV6rAQRCHXCZyi1IGpGGi
U9T2gUxmWS+uS5vxYG3KYns1WJKGqSClKAOjuO2qqKClUAorncQoA7mk8DKHnhiVKIiYS8TNSgN
kUvYLIxFiQhieIk9WKWmM7EYEzjR98-luEWw2BSxEAHzOYlVo6WWsyNzwTajlpNlttjVz52nMDV
btZv1L-t4QeEYcFsdl2BTyvVhfFJeCp-2Zut9vbqwAXSAA

UML is an abomination, but I realize that some of you may be forced by your boss to document with UML diagrams and I feel your pain, I really do. With Scribble, you can easily draw class diagrams: 


                  +------------------+
                  |NAME              |                   +---------------+
                  |Person            |                   |NAME           |
                  |--------------    |                   |Account        |
                  |ATTRIBUTES        |                   |-----------    |
                  |- name: string    |------------------>|ATTRIBUTES     |
                  |- age: int        |                   |- email: string|
                  |--------------    |                   |------------   |
                  |OPERATIONS        |                   |OPERATIONS     |
                  |+ toString: string|                   |- login        |
                  +------------------+                   +---------------+


http://buttersquid.ink/?spore=bNobwRALmBckEYHsAeYA0YXQIwA50E8YB2dCJKWAOQEEB
ZAUQB0A7ABQFMAnAZwWZYC0Q4SJEtqAFQkAlAJIAhAKoT6AZUEACZgEMAtu2gbuETgEtmAc03aL
BjeYiDRzoSwDyretMmy3ldcwA1BoQCKom5haGxmaWaGAAbjAmAK7sAL6o4BRgADbm7NzsFvFIWD
AArABs6EgATDAAzHhg+OXYdQQNHejs2jBYvXAwAAzoucgwnXkIhNBjeTncGgC8RuwQIezkLLmrI
QgWFrnsGgmm3KZw+RCE4xBJ0ABm2rlFmdkw8JO1lSStMBaZByNAY4gAxuCEClmI5mC4xMxJDIFM
o1Jp2LptKZctEIpYnAjXMwPF4fH4AgINBMLOZ4o9UhkALpAA

You can also draw those relationship diagrams that object-oriented architecture astronauts are so fond of, though Scribble doesn't support lines with open and filled diamonds because really, give me a break. 

     +----------+              +----------+
     |Company   |    contains  |Employee  |
     |--------  | O----------- |--------- |
     |Attributes|              |Attributes|
     |--------  |              |--------- |
     |Operations|O.            |Operations|
     +----------+ "\_          |          |
                    '\         +----------+
                      '\
                contains\\     +----------+
                          \\   |Product   |
                            \_ |--------  |
                             '\|Attributes|
                               |--------  |
                               |Operations|
                               +----------+


http://buttersquid.ink/?spore=bNobwRALmBckEYHsAeYA0YXQKzoJ4x0iSlgGEEBbABwEM
A7XAHToFo323mBBCCAJwCWcAK4QApgGdmHDswDyVMXxoQBCOhLRgAbjH7CxAX1TgS8ZFswBmAIx
4C6CMRhgAotQA2CXGLHSZ7Ny8giLiUqwBnHQKSipqGsxautD6RiaQLh4CdJJiAOaWNjA2ABzoSA
BMMBUAnHhF0ADseFVN6GI0MABs7XAwAAzoXpgsFUPeMCx2YB5mAMbqEDTZmkMQyanGpi4QiCjlM
Lb20DYALI7OsAAKfAgAJsJzEP4BQfxCopIvMvKKyqrqVY6PR8AxbDKwLI5CT5QrFZoYVpWQZgXA
NGwo3CtGwIjrdXoDcYjBFefAnNYuBZ0JYrLSzDagowAXSAA

Interaction diagrams, aka swimlanes, can be useful. 

     +------------+       +--------+          +--------+        +----------+
     |fabricCanvas|       |scribble|          |line seg|        |text label|
     +-----|------+       +---|----+          +---|----+        +-----|----+
 init time |                  | addToCanvas       |                   |
           |                  | ----------------->| addToCanvas       |
           |                  |                   | ----------------->|
 user moves|                  |                   |                   |
 label     | object:moving    |                   |                   |
           |----------------->|  onMove()         |                   |
           |                  |------------------>|  onMove()         |
           |                  |                   |------------------>|
           |                  |                   |                   | getCoords
           |                  |                   |                   | setCoords
           v                  v                   v                   v

http://buttersquid.ink/?spore=aNobwRALmBckEYHsAeYA0YXQEwDZ0E8Yt0IkpYBnAYwCc
BLOOAGwFM0xEkAxJgQwHMYEGgFcWAX1Thy8ZO0wAWPGELYSZGGCZ0AdiwAEFFoPSceAoaIlTImi
J3kwcCgkXUyILMvr5wWTdjM+QWhhMUlpTW09IxMMAEYYAGYABnQkLGS0lUToFxVM6HiAVnQWXhh
sljgYeIjbWGiWWPlc4uyMmHaCXPz8QpKyiugqmqL6mSaW9NyAdg7C+Z6YPoHSsHLKsrG6mw8HdK
zXaABOd019fQQdAFkEADcWAAoASn0AHR0AWh/fv//fgA+T6BZDmEIAM14TCMEzsBwwXWOxEgGlg
ULg9CoAGFeDp7rwKKDuMFLOE9lFdM1jK1avF0gN6TkVgQ1kMthsdnDYPY5IcikzVAAOc6wK5wAB
WLCoEGgAFsHrp+J8Aaq/oDieCYFCYdZIjyEZhuipatlSDJLtc7o9Xh9vmqHcCdJrSdAdbCKQa+Y
joLNBbUUebNPwWBBsQgEDQACYUT5GMMR6NE0xg13uvUNWQoflJf15UVgXhRqMAFQQuPxhJVDtVG
pTJIsbuhHv1Wcc0GKefWQdgRdL5bxBNj9pr/zrHFTjfT3Lb/OyqnyPbAujoEH0EDocrY9a1Td1M
952Z985gswLIiMNH0Csew98/hdU+bEgAukA=

And state machine diagrams are very informative, though I understand that many people would rather write a bunch of nested if statements than figure out the underlying state machine. That's perfectly fine as long as nobody loses an eye and I don't ever have to touch your code. 


                        O
                        |
                        | initial state
                        |
                        |
                        v
                    +-------+
                    |stopped|<-----------
                    +-------+           |
                        |               |
                        |               |
       receive go cmd   |               |
       ---------------  |               |
       transition actions               |
                        v               |
                    +-------+           |
                    |getting|           |  receive stop cmd
                    |ready  |           |  -----------------
                    +-------+           |  stop everything
                        |               |
                        |               |
      ---------------   |               |
      transition actions|               |
                        |               |
                        v               |
                    +-----+             |
                    |ready| ------------|
                    +-----+


http://buttersquid.ink/?spore=bNobwRALmBcYDYEsB2BTAzig5mANGAHgIwwBMALHviaRW
AJ7HQl53XQDseKAhjAGxcARjEJ44Ae3ykx4ujAAMYqLGQIICbnAAEaCNwgpc8CADcYEAE4BXFAF
8c4ZZEGSjUpovowAHHgj4nXXEAB2CUABMjM2hLG3tHGHhkdCw3RnJKNgz6RkJRejZCATAeBSERG
XcAWkJOeFky40SLFABjFAQTFC1McS1WgFtwgB0kKvGJyanRy24kNDUEcSQtblb1ZbQjOFNzazsH
SESIFylKUk85aFq-AMTMFAh1JExRlu5wuTxo2IOE2EQqAw2Eo6V8BDYZEuYJYWXBpWgnhQwkRlR
gVVoEiu+R2iTQWgAvDpHloDAFRtoiRBxJhMHBuiYEAtBIgIF9jNEAGaaDDxI4A5LAtIwKGZEXQ0
jg1gwACcXF4qJKKM8EncAGYZFcVU4Wu1Ot0gsF+kNRlMzWbRoatCguhY6BAABbIEEcvZxQ5OQEp
F1EUhyiHiliMf3S6D+hH5ZGNVXozENa5KPGE4kQUkoclISmkml0hlMhAstTsnZcnl-fnOVznDws
Uh1fw6nifKJu8uewWpUE0MVMWgMUj5UMkYoIpEonGuaA1cFY9E4pym83mmYWOYLDYrNYbrZKH77
WwAXSAA