Designing documentation and technical emails
A few years ago, I was working on a project where a part was done by a team in London, and the other part was developed in France. To communicate, we were using among others the WebHooks, for the sole reason that our technical lead wanted to use it, and back then, Microsoft's library for WebHooks was absolutely terrible: poorly documented, poorly implemented, bloated, and full of non-intuitive things. This meant that not only we had to reimplement a lot of functionality from scratch, but also that from time to time, we had problems making two applications communicate with each other. Collaboration between two teams wasn't always easy, and proving that the communication issues come from the other team wasn't the easiest thing to do.
At some point, I was working on such problem for a week or two, and figured out the root cause. Explaining it to the other team wasn't easy, however. The thing was pretty technical, and so I wrote a detailed email, trying to make it as clear as possible. The person who was working on this problem in London understood my explanations, and fixed the issue, and I thought that nobody would mention nor this problem, nor my email any longer. I was wrong.
Few days later, a guy from another team was talking with my colleague about something totally unrelated. Then, my colleague mentioned my email, and the guy exclaimed: “OK, so what is that email? I've heard everyone talking about it for days!” It appeared that while I completely forgot about the email, people around found it rather unusual, and started to forward it to their colleagues. And a bit unusual it was.
In fact, whenever I write documentation or emails, I end up using a bunch of techniques that my colleagues don't use. I find it unfortunate, as those techniques can improve a lot the content, making it easier to read and to understand. This article describes those techniques. If you write technical content on daily basis, feel free to use them.
1. Unicode characters
There was a time where ASCII was the only thing you get. Fortunately, we have two things now: Unicode, and global and mostly uniform support of Unicode. The second point is important: it is because Unicode mostly works everywhere then one can actually use it. I can write the Markdown source of an article in vim on Linux, then open it in Visual Studio Code, copy it to Chromium, and then display it on Safari on an iPad, and it will work. That is so amazing.
Two things are however truly unfortunate.
The support of Unicode is mostly uniform. That is, some applications and operating systems do well; others—not so much. And as it is not an option to ask everyone to finally stop using Windows, there is an option: either to systematically check if a piece of writing is shown correctly in Windows, or just assume that those display problems are the problems of Windows users. None of those two options is ideal.
Our keyboards contain no Unicode symbols, and there is no simple and uniform way to enter Unicode symbols. Yes, I know about Alt codes. But it is neither simple, nor uniform. While I can remember half a dozen codes, I won't be able to remember dozens. Moreover, Linux uses some alternative thing, and I don't even remember how to use it. In my case, I ended up doing a web page containing the characters I use the most. While this is very intuitive, it is burdensome to switch to this page every time I need to add an Unicode character.
Nevertheless, if you found a way to use a bunch of Unicode characters, you'll find that it may improve the technical content. See, if you're talking about resolutions, 1920×1080 looks better than 1920x1080, because there shouldn't be any “x” out there, but an actual multiplication sign. Similarly, if you talk about apertures, it's 𝑓/5.6, not f/5.6, and very tiny little distances are measured in μm, not “um.” An interesting thing is non-printable characters. This blog, for instance, uses a lot of soft hyphens to… well, hyphenate the content, and on occasions, I've used the non-breaking space to prevent the text from going on a next line when it is not supposed to do so.
Another possible use of Unicode characters is purely decorative: squares, arrows, exclamation points in yellow triangles, all that could make the content more readable.
While I haven't found a useful case where I would use generic icons (you know, the ones with a diskette, or the network switch, or a cloud), I definitively used the small logotypes to enhance documentation. For instance, a few years ago, I worked on documentation page which cross-linked a lot of resources. Adding 24×24 icons corresponding to the logotypes of the linked resources helped identifying them easier. Similarly, I was working a year ago on a documentation page which listed all the data sources a given product uses. As it was essential to differentiate between SQL Server databases, Oracle databases, and everything else, adding icons helped.
3. Syntax highlighting
One thing that annoys me a lot in development-related books is when the source code doesn't use syntax highlighting. I mean, it is not like if most studies have shown that syntax highlighting is perfectly useless: it is useful, and there are no doubts that it makes it much easier to read a piece of code.
In most cases, it doesn't take too much effort to use syntax highlighting. In emails, for example, text can be copied from an IDE, preserving the color schema. In situations where the content is generated—such as on this blog—syntax highlighting can be added explicitly. For instance, I even modified the blog engine to ensure that not only code blocks, but also inline code such as
const x = 42; would get the colors it deserves, automatically.
Some information is easier to explain through a diagram or a drawing. There are plenty of software products to make diagrams, ranging from the excellent free online tool which is very easy to use, to complex and expensive software such as Adobe Illustrator.
While it requires some time to learn to use them, and more importantly to learn to create good diagrams, it is the time well spent. For those of you who are already familiar with those tools, I can recommend the books of Edward Rolf Tufte which explain how information should be presented.
Sometimes, using those tools is just not possible. Either a person doesn't want to learn how to use them (which is perfectly understandable), or a given company doesn't want to purchase expensive licenses for products such as Adobe Illustrator, but doesn't want either the employees to use the web-based editors. In this case, nothing prevents from drawing. Five years ago, I explained that a simple piece of paper and a pen are perfectly valid tools to create diagrams. I used them in several projects in documentation and emails to a great success. It is sometimes surprising how powerful and flexible this approach can be.
Sometimes, diagrams contain source code. On several occasions, I had to explain something very specific in the pieces of source code, and the best way was to actually convert the source to vector format, and draw above it, around it, below it. While this approach is very powerful, it comes at a cost: I found no way to copy the code from an IDE to a vector application while preserving syntax highlighting. As I worked with short excerpts, I just walked through the code, manually adding color, which can be done in less than a minute. However, this is still annoying to do, and if someone knows how to avoid it, please tell.
I have seen several uses of photographs.
In one team, a product owner was taking photographs of the board, making it possible for the persons who were unable to come to see the post-its in the office to still know how things are going on.
On many occasions, I've also seen persons taking photos of the whiteboards after a meeting. Excellent way to document stuff, without actually spending an hour in Adobe Illustrator.
I have used photographs of objects where their visual could help someone to find them. One such example, although at the moment of writing, there are just a handful of photos there, is the page which documents how to use the electronic devices in one of my personal projects. Having the photos of those devices makes it easier to identify them, when I may forget what AHT21 or GY-ML8511 refers to.
Being able to take professional photographs with professional gear helps to get the wow factor—good looking photos are always nice to see. This being said, there is nothing wrong in taking a photo of a whiteboard with an old smartphone and post it to an internal Wiki.
Note that each photograph should help the reader, not just distract him. It became fashionable in many blogs to put a huge stock photo at the top, the photo having nothing to do with the article. This practice is just blatant unprofessionalism, showing a deep misunderstanding of design. It should be avoided.
Pieces of code, figures, and photographs can sometimes be annotated. Often, when providing a figure, I need to explain some parts of it. The easiest way I could find is to use small digits in circles: one such digit goes in the diagram, and the other one is mentioned in the text, like this: 1. This makes it really easy to visually find what the text is talking about. Here's an example.
Sometimes, I needed to do two types of references. I would consider this as a sign that stuff gets really complicated, but I haven't found any way to make it simpler. In this case, it is important to have at least two, and possibly all three differentiating elements among: color, categories of characters, and shape. For instance, there may be some digits in blue circles, and capital letters in orange squares.
7. Visual style
Great care should be taken regarding the visual style of a Wiki, and email, etc. Just like a book, they need to have proper headings, differentiate between bulleted list and numbered list, present tables as tables, use paragraphs, etc. The structure of the email of a piece of documentation should be clear just by looking at how the presentation.
Similarly, one should be careful when presenting individual elements. Visual hints should make it possible to understand the type of an element. For instance, if I write documentation where I instruct the user to click on Ctrl+Tab ↹, the presentation itself helps the user, whereas telling that one needs to press the control key and the tab key is not exactly visually helpful. A simple border, a few rounded corners and an Unicode character are all it gets to make it much more pleasant to read.