Introducing... a pen

Arseni Mourzenko
Founder and lead developer
May 8, 2017
Tags: communication 27 productivity 36

In most pro­jects, soon­er or lat­er, some­one asks him­self which tool should be used to make di­a­grams. It may be that the team wants to doc­u­ment their ar­chi­tec­ture, or ex­plain some­thing to a cus­tomer, or... what­ev­er. Long sto­ry short, one needs to do a draw­ing which will be in­cor­po­rat­ed into a doc­u­ment such as a Wiki or a readme or a sim­ple PDF ex­plain­ing a con­cept.

When the sub­ject is brought to a meet­ing, every­one starts sug­gest­ing their fa­vorite tool. Some sug­ges­tions such as Adobe Il­lus­tra­tor or ap­ply to vir­tu­al­ly every sit­u­a­tion; oth­ers are more gener­ic, and a tool which is specif­i­cal­ly de­signed for UML se­quence di­a­grams will hard­ly help when you need to draw a schema ex­plain­ing an ar­chi­tec­ture of a com­po­nent. Some tools are paid; oth­ers are free. Some of them re­quire months of learn­ing. For oth­ers, the user may be quite ef­fi­cient with­in min­utes.

But all those tools are miss­ing a point.

The pri­ma­ry goal of a di­a­gram is to show a thing which would be rather dif­fi­cult to ex­plain with words. UML's use case di­a­grams or ac­tiv­i­ty di­a­grams or even se­quence di­a­grams can all be de­scribed through text, but those di­a­grams are able to vi­su­al­ly trans­mit in­for­ma­tion much more ef­fec­tive­ly. Of­ten, a glimpse on a di­a­gram is enough to un­der­stand what's go­ing on, while the tran­script of the di­a­gram would take a bunch of para­graphs, if not the whole page.

The sec­ondary goal, for a de­vel­op­er, is to be able to cre­ate the di­a­gram in a short amount of time. While it is true that doc­u­men­ta­tion, when read, is read much more times than it's writ­ten, it doesn't mean that spend­ing hours on a di­a­gram would ben­e­fit the team—and so the com­pa­ny.

How do dif­fer­ent tools re­spond to those goals?

When it comes to the first goal, there is lit­tle dif­fer­ence be­tween those tools—it's rather the job of the per­son who de­signs a di­a­gram to think about a way to make the di­a­gram ex­plic­it and self-ex­plana­to­ry.

If spe­cial­ized tools have the ben­e­fit of forc­ing the user to com­ply with the giv­en rules (which can be re­al­ly con­fus­ing when it comes to UML!), they could also di­vert the at­ten­tion of the user from the goal it­self, by putting too much fo­cus on a spe­cif­ic type of the di­a­gram, while an­oth­er one could be much more ex­pres­sive.

I also no­ticed that users of any tools, in­clud­ing the ones which are ex­pect­ed to be easy to use even for new­bies, are too afraid to ex­per­i­ment with dif­fer­ent ways of ex­press­ing the same con­cept. They stick with their orig­i­nal idea, and fo­cus on re­al­iza­tion, i.e. the col­or and shad­ow of the blocks, the weight of the ar­rows, etc. While those are all im­por­tant as­pects, it's easy to miss the fact that the whole thing is plain­ly wrong.

If for the first goal, dif­fer­ent tools could hard­ly be com­pared, things should be rad­i­cal­ly dif­fer­ent when it comes to the sec­ond goal, since those tools were specif­i­cal­ly built with pro­duc­tiv­i­ty in mind. Ide­al­ly, the tool which is the sim­plest and fastest to use will win—giv­en that de­sign­ing a tool which re­sponds to every pos­si­ble use case is vir­tu­al­ly im­pos­si­ble.

I've test­ed my­self a dozen of dif­fer­ent tools, and found that, in­deed, with­out pri­or ex­pe­ri­ence in any of them, my pro­duc­tiv­i­ty gap could eas­i­ly achieve a fac­tor of ten. Learn­ing one of the tools would shift and some­times in­crease the gap.

How­ev­er, with all my re­spect for sim­ple and in­tu­itive tools which let me do my job and are of­ten avail­able for free, I find them too cum­ber­some. I al­ways end up spend­ing more time us­ing the tool rather than think­ing about my di­a­gram, and I can hard­ly de­tach my­self from the orig­i­nal idea of what I'm about to do, in or­der to ex­plore oth­er ap­proach­es.

If you en­counter the same is­sue, I have a so­lu­tion. Let me in­tro­duce... a pen.

Fig­ure 1 A pen—a tool to draw di­a­grams.

Be­fore you start mak­ing fun of me, let me as­sure you, oth­er peo­ple did it be­fore. Every time de­vel­op­ers start talk­ing about the tool they should use to draw a di­a­gram, I sug­gest a pen. Every time I make this sug­ges­tion, they laugh at me. This is very un­for­tu­nate, be­cause my sug­ges­tion is all but fun­ny.

Long time ago, I was in school. I en­joyed a lot of things, and one of those things was com­put­ers. I loved what a com­put­er can do, and I also loved the fact that with a bit of Word and MathType¹ skills, one could cre­ate vi­su­al­ly at­trac­tive doc­u­ments when do­ing home­work. My math­e­mat­ics teacher, how­ev­er, was of a dif­fer­ent opin­ion. She thought that com­put­ers have no place in ed­u­ca­tion, and that home­work should be done by hand. And since teach­ers have usu­al­ly lever­age, while stu­dents don't have any, I stopped typ­ing my home­work. Since then, I felt in love with La­TeX, and most schools fi­nal­ly start­ed notic­ing the glob­al shift to­wards IT. The very same shift seemed to de-em­pha­size the con­ve­nience of a pen as a tool for writ­ing and draw­ing things. In com­pa­nies, its us­age was de fac­to lim­it­ed to draft­ing some­thing ugly while ex­plain­ing a con­cept to a col­league.

What we are for­get­ting is that a pen re­mains an ex­cel­lent tool for cre­at­ing di­a­grams. Not draft­ing, but ac­tu­al­ly cre­at­ing the ones which can be em­bed­ded in doc­u­men­ta­tion.

I did it my­self on sev­er­al oc­ca­sions. My ma­jor ex­pe­ri­ence was a few years ago when I was in charge of the de­sign of a new prod­uct. Since there were many new things, ex­plain­ing what's go­ing on was cru­cial so that de­vel­op­ers could clear­ly un­der­stand how the prod­uct will work. So I did a lot of doc­u­ments with a lot of di­a­grams, near­ly all of them made by hand. In­te­grat­ed as il­lus­tra­tions, they were of a great help, and they looked “pro­fes­sion­al” enough, while tak­ing prac­ti­cal­ly no time at all. Some were small, lim­it­ed to il­lus­trat­ing a tiny part of the sys­tem. Oth­ers filled a whole page. In half a dozen oth­er pro­jects, I also found an op­por­tu­ni­ty to in­cor­po­rate hand-made di­a­grams, and every time, the re­sult was a nice­ly il­lus­trat­ed doc­u­ment.

Fig­ure 2 Ex­am­ple of a draw­ing in doc­u­men­ta­tion.

The time need­ed to cre­ate those di­a­grams is rather im­pres­sive. I spent from less than a minute to thir­ty min­utes on each di­a­gram, in­clud­ing the failed at­tempts. In many cas­es, do­ing the same di­a­grams on a com­put­er would take me a hour or more. While I'm not pro­fi­cient with Adobe Il­lus­tra­tor, I find my­self quite pro­duc­tive with sim­pler soft­ware prod­ucts, and learn­ing them more will lead to only a slight gain in time.

While I did those di­a­grams for in­ter­nal doc­u­men­ta­tion only, oth­er per­sons don't hes­i­tate to in­clude such di­a­grams even in books. The ones that I re­call are The time­less way of build­ing by Christo­pher Alexan­der, and The fifth dis­ci­pline by Pe­ter M. Sen­ge. Both will gain lit­tle if di­a­grams were to be re­done with Adobe Il­lus­tra­tor: the ac­tu­al clar­i­ty could hard­ly be im­proved.

Fig­ure 3 Draw­ings in a book. The time­less way of build­ing, C. Alexan­der, page 110.

Beau­ti­ful ev­i­dence by Ed­ward R. Tufte is worth look­ing as well. Here, the di­ver­si­ty of il­lus­tra­tions let one won­der how could they pos­si­bly be done with even such gener­ic tool as Adobe Il­lus­tra­tor. The as­ton­ish­ing clar­i­ty of each draw­ing makes me ask my­self what is go­ing on when I com­pare them to most di­a­grams cre­at­ed in the past ten years with all those fan­cy soft­ware prod­ucts.

While a pen is noth­ing more than an­oth­er tool, I be­lieve it has two ben­e­fits com­pared to soft­ware-based tools:

This leads to bet­ter di­a­grams, and this is some­thing we all need.

1 This was a time when Word didn't have an equa­tion ed­i­tor, so if you need­ed to in­clude an equa­tion in a doc­u­ment, ei­ther you learned La­TeX, or you had to use a third-par­ty equa­tion ed­i­tor which, luck­i­ly, in­te­grat­ed it­self in Word.