Diagrams in Documentation (Markdown Guide)
Technical writing is not only about texts — it also requires visual content, for example, graphics. However, not all technical writers can draw well, or it can take many hours to draw graphics manually by using graphics editor. I want to make your life easier, so I’ve gathered some resources that allow you to create graphics by using code.
However, before you start working on graphics, you need some tools:
- Atom. Atom is a desktop application built with HTML, JavaScript, CSS, and Node.js integration. It runs on Electron, a framework for building cross-platform apps using web technologies. It has a great number of features from editing texts to collaborating on code just as easy as it is to code alone, right from your editor.
- Integrate Markdown Preview Enhanced (MPE) to Atom. Markdown Preview Enhanced is an extension that provides you with many useful functionalities such as automatic scroll sync, math typesetting, mermaid, PlantUML, pandoc, PDF export, code chunk, presentation writer, etc.
However, don’t be afraid, it’s not as difficult as you may think. I’m a technical writer, remember? ;) I’ll help you.
Here are the steps:
- Download Atom.
- Install it on your computer.
- Open Atom.
- Read the welcome guide.
- Click Settings > Install.
- Find Markdown Preview Enhanced and click Install.
Then you need to disable the official markdown-preview package that is installed by default. To do this, follow these steps:
- Click Settings > Packages.
- Find markdown-preview and click Uninstall.
That’s all. You’re ready to work. Before starting, open a draft with markdown extension. Now, let’s see how you can create diagrams using this tool. I’ll provide links where you can find an interactive editor and play with it to find what code suits your needs. In my post, I just what to show you the possibilities of Markdown Preview Enhanced that I took from its documentation.
Flow Charts
With this code, you can create a minimalistic diagram.
You can also create something bright like this:
Sequence Diagrams
If you like a handwritten font, this one is for you.
But it also supports a simple theme.
Mermaid
There are three mermaid themes that you can choose from package settings.
PlantUML
You can install Graphviz (not required) to generate all diagram types.
GraphViz
Ditaa
Markdown Preview Enhanced supports ditaa that can convert diagrams drawn using ascii art (‘drawings’ that contain characters that resemble lines like | / — ), into proper bitmap graphics.
To create such a diagram, you should install Java.
Final Thoughts
As you see, creating a diagram by using code is not that hard. Just copy and paste the code of a diagram that suits your needs, add or remove some blocks and that’s it. This little trick will boost your knowledge and skills that will help you succeed in technical writing.
How did I become a technical writer? What skills do you need? Read FAQ on Technical Writing.
