Write the Docs – Draw the docs by Alicja Raszkowska

Technical communication encompasses more than just writing, and visual representation is an important part of communicating effectively. The subject of a talk called Draw the Docs was also covered at STC Summit 2019 by Elizabeth Alley and we wrote a summary of it.

Speaker Alicja Raszkowska says she learns best by drawing. She's a software engineer at Mobify but she only learned to draw a year ago. Alicja wanted to know how she could make drawing part of her job. 

Alicja first started to sketch out her ideas during work and turned some of her illustrations into internal technical documentation. Her passion is explaining technical concepts in drawings to help them be less intimidating. Since then, she now draws half her time at work – and people just assume it's part of her job.

Examples of technical zines and comics

She shared some examples of technical zines and comics including xkcd, and Julia Evans, which inspired her to start drawing.

Many of us already bring visual design elements to technical writing. For example, during Subject Matter Expert interviews when we want to illustrate a concept better. Engineers already use diagrams when they are pairing, whiteboarding, debugging, and doing retrospectives. Salespeople use diagrams and draw on the back of a napkins when in conversation with prospective customers.

So drawing already exists in the workplace, and we just need to make it more worthy of respect.

Benefits of drawing

Benefits of drawing

One way of increasing the status of drawing in the workplace is by focusing on the benefits. Drawing at work is good for many things like facilitating communication, encouraging support and learning, and making documentation more engaging and appealing.

It's also a fairly democratic practice. All you need is a paper and pencil. There's a philosophy that if you can draw a line, a circle, and a square, then you can draw anything, since all objects are made of these three basic basic elements. 

That being said, learning takes a long time and it requires failing over and over. Sometimes it's best to leave drawing to the trained designers. The designer at Mobify took Alicja's drawings and made them more professional-looking so they could be used in the official documentation. 

How to draw your ideas

Alicja makes the point that it takes time to get good at something, and people already have jobs. It's not quite as simple as 'learn to draw'. She came up with a framework to help people so they don't have to reinvent the wheel. 

People can start using drawing more in their jobs by following Alicja's 5 step master plan:

• Step 0: Draw a lot
• Step 1: Make a business case
• Step 2: Build a workflow
• Step 3: Spread the word
• Step 4: Refactor, repeat, rejoice

Sketching is important, but sometimes you need the proper tooling for diagrams. According to Alicja, diagrams should be automated in engineering workflows, ideally using open source software and version controlled. 

There's a tendency to want to build your own tools to accomplish these processes. It may not make the most sense to build your own tool, even though you do get more control over the implementation and you don't have to work around someone else's code. Since there are already many tools for producing diagrams and to help you draw things, it may not be worth investing the development and design time to create your own solution.

Alicja brings up the example of Mermaid which they use to make diagrams at Mobify. Mermaid is an open source library in Javascript and you can use it for creating diagrams in a Markdown-like syntax (Alicja previewed Mermaid on stage). They're happy with Mermaid but it's a work in progress. Her designers need to use SVGs, and Mermaid doesn't actually create a true SVG so you can't edit the exported file easily.

Making diagrams in your documentation is nothing new. Companies already produce diagrams that look more professional than using cute pictures in their documentation. It's not too much of a step for you to start drawing the docs. 

Maintaining a visual language

Once you get started with pictures and diagrams, you have to stay committed. Visual language needs to be treated as part of your company brand. You need to define it and maintain it along with the rest of your code, so it's an ongoing process. 

Engage other people in your diagrams, share them with the docs team, and use any opportunity to talk about drawing. As Alicja shared her understanding of technical concepts with the rest of the team using diagrams, she was able to get feedback that she didn't quite understand the difference between two similar tools. This made her work better and more accurate. 

As Alicja says: Refactor, repeat, rejoice.

Watch Alicja's full talk on YouTube and follow her on twitter.