DrakonHub will shut down forever on December 1, 2024 Read more...

# Learn DRAKON by Examples

## A good day

This is a very minimal DRAKON diagram. It shows a simple algorithm with only 3 steps:

1. Eat breakfast
2. Eat lunch
3. Eat dinner

The name of the diagram is in the start icon (Good day). It is located at the top of the diagram.

Each rectangular box contains an order.

The end is at the bottom.

There is no need for arrows because the next icon is always below.

## Go out

This algorithm is more complex. The boxes contain orders, as before. The truncated diamond contains a question. The diagram includes two use cases: with rain and without rain.

Use case 1: go out without rain

1. Put on clothes
2. Is it raining? No
3. Leave the house

Use case 2: go out with rain

1. Put on clothes
2. Is it raining? Yes
3. Take umbrella
4. Leave the house

Use case 2 is slightly less pleasant than use case 1. Therefore, the path related to use case 2 goes through the right part of the diagram.

The further to the right, the worse it is.

The main vertical is called the skewer. The skewer shows the happy path.

Here is another example of the rule The further to the right, the worse it is.

The happy path is the most successful scenario, the best outcome. It goes down the skewer. On this picture, success involves finding and buying the puppy.

In some cases, the words "best" and "worst" are not applicable. Then the skewer should indicate the most probable path through the algorithm.

## Take a train

When there are many verticals on a diagram, they should be sorted from left to right. The best path follows the skewer. The worst path is the rightmost one. All others are somewhere in between.

Again, the further to the right, the worse it is.

In the example below, parking is one of the steps of the algorithm. There are three possibilities:

1. The free parking is available. Park for free! This is the ideal scenario. It goes straight down the skewer.
2. The free parking is not available. But the paid parking is. This is somehow worse.
3. There are no parking spots in the vicinity. Damn. We'll have to walk a long way. The worst things happen on the rightmost path.

Note that similar actions (parking) sit on the same horizontal. This is a way to show their connection. This visual trick is called common fate.

## Drunk driving in Greece

Many questions can't be answered with just a "yes" and a "no". When there are several possible answers, use the "choice" icon.

For best readability, arrange the answers: from smallest to largest, from lowest to highest, or from best to worst.

## Work out UNTIL

DRAKON diagrams do not need arrows for normal connections, plain lines are enough. Arrows are reserved for special occasions. This upward-pointing arrow represents a cycle.

We lift the weight and take a brief rest. Then we repeat until we are tired.

Note: we lift the weight at least once.

## Work out WHILE

This loop is similar to the one above. The difference is that we check for the exit condition before we perform the repeated action.

Here, we don't even start the lifting if we are already tired after the warm-up.

## Work out with FOR EACH (repeat) loop

The hamburger-shaped formation on this picture is a FOR EACH loop.

The actions inside the hamburger will be repeated several times. A typical text in a FOR EACH loop icon could look like this:

• For each person in the room
• Or: For each number in the sequence
• Or: Repeat the operation N times

In the current example, we repeat the exercise 10 times. But we quit as soon as we get tired. So the ten repetitions might or might not be completed.

## Luhn algorithm

Enough of toy diagrams. Let us take a real algorithm.

Luhn algorithm is used for verifying numbers of all payment cards in the world.

Here is the text representation of the algorithm.

1. From the rightmost digit, which is the check digit, and moving left, double the value of every second digit. If the result of this doubling operation is greater than 9 (e.g., 8 × 2 = 16), then add the digits of the product (e.g., 16: 1 + 6 = 7, 18: 1 + 8 = 9) or alternatively subtract 9 from the product (e.g., 16: 16 - 9 = 7, 18: 18 - 9 = 9).
2. Take the sum of all the digits.
3. If the total modulo 10 is equal to 0 (if the total ends in zero) then the number is valid according to the Luhn formula; else it is not valid.

The text form might be more compact than a diagram. But DRAKON strives for clarity, not compactness. It does not hide complexity. It does not force the reader to unpack hidden structures. Instead, all complexity is shown explicitly.

Each icon on a DRAKON diagram should contain only one idea.

## Register user

If there is one word that makes DRAKON special, it's silhouette.

The diagrams above are primitives. Primitives are good for simple things. But real problems are not always simple.

Silhouette is a unique feature of DRAKON that deals with complex problems. Silhouette breaks up a problem into logical parts.

Here is a video that explains silhouette.

The diagram below is a real specification for registering new users in DrakonHub.

## Lunch break

This silhouette is special. It has a branch that runs several times. The "Eat" branch is executed while we are still hungry.

Repetition implemented with a silhouette is called silhouette loop.

Here is yet another real-life algorithm. It describes logging on to a third-party website using Facebook authentication.

Many websites have a button "Logon with Facebook". Users can enter their Facebook credentials instead of making up a new password for that website.

This is easy for the user, but the technical details behind the hood are tricky. This diagram shows the underlying cooperation between the browser, the website's server and the Facebook server.