Blog >
Guidelines for drawing DRAKON flowcharts
Choose a meaningful name
Give the DRAKON flowchart a proper name that reflects its purpose.
The name should not be too long, just long enough to convey the meaning.
If the name is too short, it will be difficult to figure out what the algorithm does. Also, it will be hard to find the diagram later on, if the name does not contain the relevant keywords.
Bad example:
Check
Check what?
Bad example:
Check if the water level is sufficient or not
Too wordy.
Good example:
Check the water level
This one is better. However, if there are several methods to check the water level, add clarifying words to the names of the algorithms. Ensure that the reader sees which method to use.
One idea—one icon
Lay out the algorithm as a series of steps. One step should contain either a single order or a question. Put each of the steps into a separate icon.
Do not place more than one idea in one icon.
Too much text in one block is an indication that you are trying to lump together several thoughts. Also, watch out for commas.
If you notice multiple orders in one icon, split it up.
Use direct language
Use concise and straightforward language. For example, do not use words "shall," "will," or "should" for orders. Use direct imperative verbs.
Bad example:
The system shall check the password.
Good example:
Check the password
A formal or polite style is not always the best choice. Remember, the goal is clarity.
Beware of AND, NOT, and OR
Consider AND, NOT, and OR as parasite words when you are working on a DRAKON flowchart. Every time you run into any of those, think twice.
If an AND connects two orders in one sentence, make two icons out of it.
If it is an OR that connects the orders, that can lead to ambiguity. For example, what does "Fight or run" mean? Shall we fight or shall we run? There is a hidden decision here. Show all points of decision making explicitly.
It is allowed to use AND and OR inside orders.
Cut the belt with a knife or scissors
Here, the order is "cut." The decision making is trivial: use the tool you have.
The words AND, OR, and NOT harm questions even more than orders.
Negation is the easiest one to get rid of:
- Remove the NOT word from the question.
- Swap the Yes and No exits from the "Question" icon.
To remove AND and OR, use the visual formulas shown below.
Each of these patterns can represent either AND or NOT, depending on the situation.
Identify the actors
Define the actors that will carry out the orders.
If there is one actor for the whole algorithm, do not mention the actor in the body of the diagram. Use "Action" icons to give orders to that actor.
For example, if you are writing a business procedure for the procurement manager, do not tell him he is a procurement manager in each sentence.
If there are several actors in the algorithm, use the "Shelf" icon. Put the actor on the upper shelf and the order on the lower shelf.
If one actor sends a message to another actor, put both the sender and the receiver on the upper shelf. Separate them with an arrow, or the > sign.
If the sender of the message does not accept orders from this algorithm, the sender is not an actor in the algorithm. In such cases, use the "Input" icon.
If the receiver of the message is not part of the algorithm, use the "Output" icon.
Handle different types of questions properly
If a question can be answered as either "Yes" and "No," use the "Question" icon.
If a question can have several answers, but not too many, use the "Choice" icon.
What is "too many"? It's hard to tell accurately. Probably, eight answers are not too many yet.
But what if we have a lot of possible cases? Say, twenty or fifty?
Then do not draw them in a DRAKON chart. Create a table that maps the answers to the corresponding actions. Keep that table somewhere separately and reference it from an "Action" icon. Do not litter the diagram with excessive branching.
Don't let your diagram grow too large
Huge diagrams are hard to comprehend, so prevent their uncontrollable growth.
When can we call a diagram "too large"?
Here is a rule of thumb: while the diagram fits the screen vertically, do not do anything. When it grows taller than that, it's time to take measures.
One way to make the diagram smaller is decomposition:
- Create a new DRAKON flowchart.
- Cut out a fragment from the original flowchart and paste it into the new one.
- Add an "Insertion" icon in place of the deleted fragment.
- Put the name of the new diagram in the "Insertion" icon.
There is another extreme: having thousands of tiny diagrams. Then the problem is that the reader needs to switch between them too often if he wants to see the big picture.
Another way to fight diagram growth in DRAKON is the silhouette. The silhouette is a way to arrange several smaller flowcharts on one visual scene.
Turning a large diagram into a silhouette is reminiscent of dividing a long text into chapters.
A silhouette diagram can become broader than the screen, but it's okay. As long as the drawing fits the screen vertically, don't worry.
Show the happy path
If you have a happy path in your algorithm, show it.
Use the rule "the further to the right, the worse." According to this rule, the happy path should go straight down the leftmost vertical line. The less desired routes should take a detour through the right-hand side of the diagram.
If it's hard to call a specific outcome good or bad, then place the most probable path on the leftmost vertical. No matter what you do, do not put the worst-case scenario on the left side of the DRAKON flowchart.
Indicate invisible connections with a "common fate"
If there is an action that must be performed regardless of the conditions, use "common fate." It is another exciting feature of DRAKON. With common fate, it is possible to show a hidden relationship between icons that sit on different vertical lines.
Specify the inputs and the outputs in the "Parameters" icon
If you want to show that your algorithm has clearly defined inputs and outputs, add a "Parameters" icon to the header. List both the inputs and the outputs in the "Parameters" icon.
Put only the interesting stuff in the diagram
A DRAKON flowchart should only show the behavior which either important or non-trivial. Do not draw things just because you can. Limit the information that your reader will have to digest.
There is a good rule for writing texts: write what people will read. Here is a similar guideline for drawing diagrams: draw what people need to see.
Do not program
Programming experience may work against you when you draw flowcharts. There might come a temptation to make diagrams overly thorough. Resist that temptation.
When a diagram gets too formal, it becomes code. And code is always ugly and hard-to-read even for programmers.
Learn how to leave out the technical details and formalisms.
For example, avoid passing arguments to subdiagrams unless it is necessary.
Bad example:
Check credentials(username, password)
Good example:
Check password
It is already clear that checking credentials involves examining the password and that the password belongs to a user.
However, do specify in the "Check credentials" algorithm that it takes the username and the password as inputs. Use a "Parameters" icon for that.
Let's take another example. The user connects to the server and logs into it. After a certain period of inactivity, the connection closes automatically. Each time when the user performs an operation, he postpones his automatic logout. This way, while the user is doing something on the server, he remains connected.
A typical mistake is to insert a step "Postpone automatic logout" in every procedure that the user can run. If there are forty procedures, forty algorithms will be modified. Do not do that. Instead, insert a comment in the "Postpone automatic logout" flowchart saying "Run this on every user action." The programmers will find a way how to implement that.
One more example. A DRAKON flowchart explains how a web application works. The web application consists of the page code and the server code. These are two separate programs that work together over the network to deliver a feature.
The thing is, the end user does not care about the implementation details. Hence, the flowchart that defines the behavior of the system as a whole should not show these details. That flowchart should have a single continuous flow that does not mention any JavaScript code, server, network, threads, etc.
The less redundant information you cram in the diagram, the more readable it becomes.
Summary
- Choose a meaningful name
- One idea—one icon
- Use direct language
- Beware of AND, NOT, and OR
- Identify the actors
- Use "Action" when there is one actor
- Use "Shelf" when there are several actors
- Handle different types of questions properly
- Use "Question" for yes-or-no questions
- Use "Choice" for multiple-choice questions
- Make a table outside of the diagram if there are many answers.
- Don't let your diagram grow too large
- Use "Insertion" for decomposition
- Use the silhouette to create chapters
- Show the happy path
- Indicate invisible connections with a common fate
- Specify the inputs and the outputs in the "Parameters" icon
- Put only the interesting stuff in the diagram
- Do not program
As one can see, these guidelines are somewhat more advanced than elemental diagramming rules like "avoid line intersections." Following the above points demands some experience and taste.
DrakonHub does the tedious work for you, takes care of alignment, centering, spacing, basic rules of DRAKON, etc. And you can concentrate on your ideas, use your experience and taste.
