Designing documentation and technical emails

Arseni Mourzenko
Founder and lead developer
176
articles
July 28, 2021
Tags: visual-design 1 information-design 1 communication 27 quality 36

A few years ago, I was work­ing on a pro­ject where a part was done by a team in Lon­don, and the oth­er part was de­vel­oped in France. To com­mu­ni­cate, we were us­ing among oth­ers the Web­Hooks, for the sole rea­son that our tech­ni­cal lead want­ed to use it, and back then, Mi­crosoft's li­brary for Web­Hooks was ab­solute­ly ter­ri­ble: poor­ly doc­u­ment­ed, poor­ly im­ple­ment­ed, bloat­ed, and full of non-in­tu­itive things. This meant that not only we had to reim­ple­ment a lot of func­tion­al­i­ty from scratch, but also that from time to time, we had prob­lems mak­ing two ap­pli­ca­tions com­mu­ni­cate with each oth­er. Col­lab­o­ra­tion be­tween two teams wasn't al­ways easy, and prov­ing that the com­mu­ni­ca­tion is­sues come from the oth­er team wasn't the eas­i­est thing to do.

At some point, I was work­ing on such prob­lem for a week or two, and fig­ured out the root cause. Ex­plain­ing it to the oth­er team wasn't easy, how­ev­er. The thing was pret­ty tech­ni­cal, and so I wrote a de­tailed email, try­ing to make it as clear as pos­si­ble. The per­son who was work­ing on this prob­lem in Lon­don un­der­stood my ex­pla­na­tions, and fixed the is­sue, and I thought that no­body would men­tion nor this prob­lem, nor my email any longer. I was wrong.

Few days lat­er, a guy from an­oth­er team was talk­ing with my col­league about some­thing to­tal­ly un­re­lat­ed. Then, my col­league men­tioned my email, and the guy ex­claimed: “OK, so what is that email? I've heard every­one talk­ing about it for days!” It ap­peared that while I com­plete­ly for­got about the email, peo­ple around found it rather un­usu­al, and start­ed to for­ward it to their col­leagues. And a bit un­usu­al it was.

In fact, when­ev­er I write doc­u­men­ta­tion or emails, I end up us­ing a bunch of tech­niques that my col­leagues don't use. I find it un­for­tu­nate, as those tech­niques can im­prove a lot the con­tent, mak­ing it eas­i­er to read and to un­der­stand. This ar­ti­cle de­scribes those tech­niques. If you write tech­ni­cal con­tent on dai­ly ba­sis, feel free to use them.

1. Uni­code char­ac­ters

There was a time where ASCII was the only thing you get. For­tu­nate­ly, we have two things now: Uni­code, and glob­al and most­ly uni­form sup­port of Uni­code. The sec­ond point is im­por­tant: it is be­cause Uni­code most­ly works every­where then one can ac­tu­al­ly use it. I can write the Mark­down source of an ar­ti­cle in vim on Lin­ux, then open it in Vi­su­al Stu­dio Code, copy it to Chromi­um, and then dis­play it on Sa­fari on an iPad, and it will work. That is so amaz­ing.

Two things are how­ev­er tru­ly un­for­tu­nate.

  1. The sup­port of Uni­code is most­ly uni­form. That is, some ap­pli­ca­tions and op­er­at­ing sys­tems do well; oth­ers—not so much. And as it is not an op­tion to ask every­one to fi­nal­ly stop us­ing Win­dows, there is an op­tion: ei­ther to sys­tem­at­i­cal­ly check if a piece of writ­ing is shown cor­rect­ly in Win­dows, or just as­sume that those dis­play prob­lems are the prob­lems of Win­dows users. None of those two op­tions is ide­al.

  2. Our key­boards con­tain no Uni­code sym­bols, and there is no sim­ple and uni­form way to en­ter Uni­code sym­bols. Yes, I know about Alt codes. But it is nei­ther sim­ple, nor uni­form. While I can re­mem­ber half a dozen codes, I won't be able to re­mem­ber dozens. More­over, Lin­ux uses some al­ter­na­tive thing, and I don't even re­mem­ber how to use it. In my case, I end­ed up do­ing a web page con­tain­ing the char­ac­ters I use the most. While this is very in­tu­itive, it is bur­den­some to switch to this page every time I need to add an Uni­code char­ac­ter.

Nev­er­the­less, if you found a way to use a bunch of Uni­code char­ac­ters, you'll find that it may im­prove the tech­ni­cal con­tent. See, if you're talk­ing about res­o­lu­tions, 1920×1080 looks bet­ter than 1920x1080, be­cause there shouldn't be any “x” out there, but an ac­tu­al mul­ti­pli­ca­tion sign. Sim­i­lar­ly, if you talk about aper­tures, it's 𝑓/5.6, not f/5.6, and very tiny lit­tle dis­tances are mea­sured in μm, not “um.” An in­ter­est­ing thing is non-print­able char­ac­ters. This blog, for in­stance, uses a lot of soft hy­phens to… well, hy­phen­ate the con­tent, and on oc­ca­sions, I've used the non-break­ing space to pre­vent the text from go­ing on a next line when it is not sup­posed to do so.

An­oth­er pos­si­ble use of Uni­code char­ac­ters is pure­ly dec­o­ra­tive: squares, ar­rows, ex­cla­ma­tion points in yel­low tri­an­gles, all that could make the con­tent more read­able.

2. Lo­go­types

While I haven't found a use­ful case where I would use gener­ic icons (you know, the ones with a diskette, or the net­work switch, or a cloud), I de­fin­i­tive­ly used the small lo­go­types to en­hance doc­u­men­ta­tion. For in­stance, a few years ago, I worked on doc­u­men­ta­tion page which cross-linked a lot of re­sources. Adding 24×24 icons cor­re­spond­ing to the lo­go­types of the linked re­sources helped iden­ti­fy­ing them eas­i­er. Sim­i­lar­ly, I was work­ing a year ago on a doc­u­men­ta­tion page which list­ed all the data sources a giv­en prod­uct uses. As it was es­sen­tial to dif­fer­en­ti­ate be­tween SQL Serv­er data­bas­es, Or­a­cle data­bas­es, and every­thing else, adding icons helped.

3. Syn­tax high­light­ing

One thing that an­noys me a lot in de­vel­op­ment-re­lat­ed books is when the source code doesn't use syn­tax high­light­ing. I mean, it is not like if most stud­ies have shown that syn­tax high­light­ing is per­fect­ly use­less: it is use­ful, and there are no doubts that it makes it much eas­i­er to read a piece of code.

In most cas­es, it doesn't take too much ef­fort to use syn­tax high­light­ing. In emails, for ex­am­ple, text can be copied from an IDE, pre­serv­ing the col­or schema. In sit­u­a­tions where the con­tent is gen­er­at­ed—such as on this blog—syn­tax high­light­ing can be added ex­plic­it­ly. For in­stance, I even mod­i­fied the blog en­gine to en­sure that not only code blocks, but also in­line code such as const x = 42; would get the col­ors it de­serves, au­to­mat­i­cal­ly.

3. Fig­ures

Some in­for­ma­tion is eas­i­er to ex­plain through a di­a­gram or a draw­ing. There are plen­ty of soft­ware prod­ucts to make di­a­grams, rang­ing from the ex­cel­lent free on­line tool which is very easy to use, to com­plex and ex­pen­sive soft­ware such as Adobe Il­lus­tra­tor.

While it re­quires some time to learn to use them, and more im­por­tant­ly to learn to cre­ate good di­a­grams, it is the time well spent. For those of you who are al­ready fa­mil­iar with those tools, I can rec­om­mend the books of Ed­ward Rolf Tufte which ex­plain how in­for­ma­tion should be pre­sent­ed.

Some­times, us­ing those tools is just not pos­si­ble. Ei­ther a per­son doesn't want to learn how to use them (which is per­fect­ly un­der­stand­able), or a giv­en com­pa­ny doesn't want to pur­chase ex­pen­sive li­cens­es for prod­ucts such as Adobe Il­lus­tra­tor, but doesn't want ei­ther the em­ploy­ees to use the web-based ed­i­tors. In this case, noth­ing pre­vents from draw­ing. Five years ago, I ex­plained that a sim­ple piece of pa­per and a pen are per­fect­ly valid tools to cre­ate di­a­grams. I used them in sev­er­al pro­jects in doc­u­men­ta­tion and emails to a great suc­cess. It is some­times sur­pris­ing how pow­er­ful and flex­i­ble this ap­proach can be.

Some­times, di­a­grams con­tain source code. On sev­er­al oc­ca­sions, I had to ex­plain some­thing very spe­cif­ic in the pieces of source code, and the best way was to ac­tu­al­ly con­vert the source to vec­tor for­mat, and draw above it, around it, be­low it. While this ap­proach is very pow­er­ful, it comes at a cost: I found no way to copy the code from an IDE to a vec­tor ap­pli­ca­tion while pre­serv­ing syn­tax high­light­ing. As I worked with short ex­cerpts, I just walked through the code, man­u­al­ly adding col­or, which can be done in less than a minute. How­ev­er, this is still an­noy­ing to do, and if some­one knows how to avoid it, please tell.

4. Pho­tographs

I have seen sev­er­al uses of pho­tographs.

  1. In one team, a prod­uct own­er was tak­ing pho­tographs of the board, mak­ing it pos­si­ble for the per­sons who were un­able to come to see the post-its in the of­fice to still know how things are go­ing on.

  2. On many oc­ca­sions, I've also seen per­sons tak­ing pho­tos of the white­boards af­ter a meet­ing. Ex­cel­lent way to doc­u­ment stuff, with­out ac­tu­al­ly spend­ing an hour in Adobe Il­lus­tra­tor.

  3. I have used pho­tographs of ob­jects where their vi­su­al could help some­one to find them. One such ex­am­ple, al­though at the mo­ment of writ­ing, there are just a hand­ful of pho­tos there, is the page which doc­u­ments how to use the elec­tron­ic de­vices in one of my per­son­al pro­jects. Hav­ing the pho­tos of those de­vices makes it eas­i­er to iden­ti­fy them, when I may for­get what AHT21 or GY-ML8511 refers to.

Be­ing able to take pro­fes­sion­al pho­tographs with pro­fes­sion­al gear helps to get the wow fac­tor—good look­ing pho­tos are al­ways nice to see. This be­ing said, there is noth­ing wrong in tak­ing a pho­to of a white­board with an old smart­phone and post it to an in­ter­nal Wiki.

Note that each pho­to­graph should help the read­er, not just dis­tract him. It be­came fash­ion­able in many blogs to put a huge stock pho­to at the top, the pho­to hav­ing noth­ing to do with the ar­ti­cle. This prac­tice is just bla­tant un­pro­fes­sion­al­ism, show­ing a deep mis­un­der­stand­ing of de­sign. It should be avoid­ed.

5. An­no­ta­tions

Pieces of code, fig­ures, and pho­tographs can some­times be an­no­tat­ed. Of­ten, when pro­vid­ing a fig­ure, I need to ex­plain some parts of it. The eas­i­est way I could find is to use small dig­its in cir­cles: one such dig­it goes in the di­a­gram, and the oth­er one is men­tioned in the text, like this: 1. This makes it re­al­ly easy to vi­su­al­ly find what the text is talk­ing about. Here's an ex­am­ple.

Some­times, I need­ed to do two types of ref­er­ences. I would con­sid­er this as a sign that stuff gets re­al­ly com­pli­cat­ed, but I haven't found any way to make it sim­pler. In this case, it is im­por­tant to have at least two, and pos­si­bly all three dif­fer­en­ti­at­ing el­e­ments among: col­or, cat­e­gories of char­ac­ters, and shape. For in­stance, there may be some dig­its in blue cir­cles, and cap­i­tal let­ters in or­ange squares.

7. Vi­su­al style

Great care should be tak­en re­gard­ing the vi­su­al style of a Wiki, and email, etc. Just like a book, they need to have prop­er head­ings, dif­fer­en­ti­ate be­tween bul­let­ed list and num­bered list, pre­sent ta­bles as ta­bles, use para­graphs, etc. The struc­ture of the email of a piece of doc­u­men­ta­tion should be clear just by look­ing at how the pre­sen­ta­tion.

Sim­i­lar­ly, one should be care­ful when pre­sent­ing in­di­vid­ual el­e­ments. Vi­su­al hints should make it pos­si­ble to un­der­stand the type of an el­e­ment. For in­stance, if I write doc­u­men­ta­tion where I in­struct the user to click on Ctrl+Tab ↹, the pre­sen­ta­tion it­self helps the user, where­as telling that one needs to press the con­trol key and the tab key is not ex­act­ly vi­su­al­ly help­ful. A sim­ple bor­der, a few round­ed cor­ners and an Uni­code char­ac­ter are all it gets to make it much more pleas­ant to read.