1. Home
2. Blog
3. Documentation in Pictures

Today I want to confess my faults as a programmer.

I am a lazy developer.
I don’t like wasting time on extensive debugging.
I don’t like inventing any integration hacks. I am too lazy to use temporary solutions because anyway they will have to be reworked later on.
I don’t like wasting time to explain the architecture of one and the same business component to developers working on different platforms.

I am a visual learner but I can’t draw well.
I like devouring information with pictures more than reading text extracts only. I’m not very good at drawing by hand, and too lazy to install and use sophisticated tools.

I am a retrograde and a bore.
I like old and time-proved tools. I like accuracy and unambiguity, because I am too lazy to deal with uncertainties. And I also like it very much when changes in documentation can be easily tracked.

Thus, in the process of production and under the influence of my own personal traits mentioned above, I have come to the conclusion that the best way to make up documentation and distribute it among developers, project/product managers, and quality assurance team is in the form of graphical resources.

Salvation.

Surfing the Internet in search for a solution to my problem, I have found a lot of help from Graphviz and DOT. Using the DOT language you can easily describe diagrams and graphs which will represent the architecture of similar components for web, iOs, and Android, and render it into whatever format you like – png/svg/jpeg. There are a lot of plugins for DOT: for IDE, web services like Confluence. And it means that you can visualize a document not only from the command line but also inside standard applications.

Besides, DOT is very good to describe finite state machines => to do away with uncertainties and the need to think about it. And of course, since DOT is a language, any changes in a text file containing a component description with any version control system will be fixed automatically.

See below what you can do with help of DOT and Graphviz.

And here is the textual representation: 

This approach has often helped me both in the development process and in conducting presentations. Using this tool, I managed to quickly and easily represent a diagram/flowchart and to make the required changes. The DOT language is rather simple and quite easy to learn.

Most of all I like the option to focus primarily on the content, not the representation – all graphical elements will be drawn and arranged automatically, and you will not need to rearrange blocks after making changes.

P.S. I fibbed a little: I don’t like temporary solutions because there is nothing more permanent than temporary. I hope this tool and approach will help you save some time.

Ivan Alyakskin 
Software Consultant