Arts of drawing technical diagrams for beginners

TL;DR

Don't draw diagrams.

Problem of beginners

In Software Development, we often have to use some kind of diagrams to communicate our design among team members. It is not difficult to learn about them as there are a lot of resources out there. But knowing the syntax doesn't mean you can use it properly.

It is fortunate for me to have many chances to do the system design of various kinds, and use diagrams to tell the team what to do. I failed desperately, however, in my first time due to a reason which I believe is a common pitfall for most beginners.

Beginners usually start the job by thinking "what are the canonical documents and diagrams I have to prepare?". What they have in mind is like some kind of a "complete blueprint" of an entire building. They may remember learning from Software Design classes about some standard Software Specification Document and UML Diagrams. They spend weeks trying to write a document for the "entire system", but fail to make people understand what to do.

It took me some time to realize the gotcha, which is surprisingly simple: You want communication, not a diagram.

What are you trying to say

"I have something to write, so I write." This is the answer I got, in my childhood, from a professional writer when I asked him how to become a writer. It was to point out that the beginners usually think in the wrong direction, i.e. they write because they have to or want to write something great, the result of the which usually becomes some kind of beautiful-but-meaningless medium.

I believe this applies to any kind of communication practitioner. It is not easy to find good content to write in literature. But in Software Development, this is quite obvious. The meaning of your communication is so that your audience will be able to build a software product as close as possible to your imagination.

If you are designing and building the system all by yourself, you don't need communication. You know what you want. But when things need to be delegated among various roles and responsibilities, you have to explain what you want aloud, what you are trying to do if it were you.

In reality, however, you don't know everything. The team is there because someone is more specialized than you in some area. For example, you may have no idea what information the infra team needs to know.

Go asking. is what I would like to conclude this section with. Instead of sitting alone drawing some beautiful diagrams, find your audience, explain your initial idea and ask what they need to know to be able to start working.

Start by talking

Let's assume you now have something to explain in your head. The next step is to start thinking about which communication methods are efficient.

"Premature optimization is the root of all evils". This can be true in our situation too. Talking is the cheapest way to communicate. If it can get the job done, why bother and waste time devising a beautiful diagram or presentation?

When the content is too complex for talking, that is the moment to start finding useful tools to help fill the gap, because that is the only time when the gap reveals, otherwise you may be trying to fill a gap that doesn't exist.

Use any kind of medium

A diagram is just a kind of medium, and its job is to help with your communication. But don't limit yourself, your medium can be some stupid drawing, placing objects on the table while you explain, or using some existing website as an example.

For a beginner, you may have to do some experiments. Try out different methods and diagrams and see what works best in which situation.

Understanding, Not Instructions

A common mistake when beginners write a diagram is to put too much information into it. When I was a beginner, I supposed it is my responsibility to define the complete database relations and columns. I was paranoid and try to put every possible case in a sequence diagram. I tried to list out all API interfaces, and so on. I have a misunderstanding that developers will do what are and only are, stated in my documents.

It turned out the development team doesn't work like that. One reason is that things will change and you will never be able to design everything up-front. Another point is that you are not and should not be an instruction writer for developers. There are many ways to solve a problem, and it is to be decided by everyone and revised over and over during the development cycles.

Again the team is there because someone is specialized in stuff you don't. Testers can be better at listing out the possible cases to test. Developers know much more details about the implementation than you, and so on.

How many details you should put in your design will vary for different teams and individuals you are dealing with. The point is to make people with different responsibilities understand the same thing, can start working with enough information, and finally can integrate correctly.

This job needs the skill to understand your audience.

Be prepared, therefore improved

We are beginners because we are not sure what is right or wrong, and so we strive for some fixed procedures or tools to be safe, but they are not the solution. That is why I put in the TL;DR section "Don't draw diagrams", but that is exaggerated. I want to invite you to spend less effort to make your "medium" follow some standards, and focus more on the people you are dealing with.

Whatever I have said, I still find that a drawing or diagram is a necessary part of an efficient discussion, it serves as a map to prevent us to get lost. So, don't approach people or arrange a meeting unprepared. Even at high uncertainty, always prepare some version of drawing to show what you think is right. Don't fear that it will be wrong, because it will. Don't fear that you will have to revise it, you will. People work better to fix stuff in the paper, not in the air.