Blog >

How to create software requirements specification using DRAKON

by Stepan Mitkin

21 May 2018

Request a precise problem statement

Software requirements start with a problem statement. A precise problem statement is a mandatory input for creating requirements. If the client has not provided a problem statement, write one and get the client to approve it.

The problem statement should be a short text, preferably bullet points.

Example:

  • Implement password authentication on the website.
  • During login, replace the current session with a new one.
  • After a successful login, attach the new session to the user record.
  • After a successful login, show a personalized start page.
  • After a successful login, close all other sessions of the user.
  • The system automatically logs the user off after a period without activity.
  • If the user has entered an invalid password three times, block the user.
  • Make a 3-second pause between password checks.

Images and lists instead of prose

The less plain text there is in the requirements, the better. Instead of writing text, draw diagrams, put together lists and tables.

The requirements will consist of the following documents:

  • DRAKON flowcharts that represent the behavior of the software. Most of the complexity of a software system lies in its behavior. Therefore, DRAKON flowcharts will constitute most of the requirements.
  • A description of the logical data structure of the system.
  • The input and output data formats.
  • User interface sketches.
  • Acceptance tests.

This article explains how to draw DRAKON flowcharts for software requirements specification. To learn how to write acceptance tests from DRAKON flowcharts, read this: link.

Find the entry points

Look at the program as at a black box that does nothing until it gets a shock from the outside world. There are events in the outside world that set the program in motion. These events are the entry points into the system.

Build a list of entry points. For every entry point, there will be an algorithm that the program will follow to react to the event.

Entry points break up the solid body of the program into pieces following the principle of divide and conquer.

Finding all entry points is crucial. It is not always easy because some entry points are not immediately visible.

Let's take the example with login into a website. The first entry point is "Login with a password." The user presses the "Login" button and authenticates. This one is quite clear.

"The system automatically logs the user off after a period without activity." This statement hides an additional entry point—logout on timeout. Logout on timeout is notable because it will happen in the future.

When the algorithm schedules a future action, that action is also an entry point. In this case, the external shock comes from the alarm clock, not from the user. In spite of this difference, document and test the entry points of postponed actions thoroughly, as usual.

"Postpone logout on timeout" is another entry point. The user postpones his automatic logout with his every action on the website. The problem statement does not mention it explicitly, so this entry point is easy to miss.

Entry points:

  • Login with a password
  • Logout on timeout
  • Postpone logout on timeout

Draw a DRAKON flowchart for every entry point

An external shock comes into an entry point and starts a process. One top-level DRAKON flowchart and possibly several subordinate diagrams describe the algorithm of this process.

Decompose the process into steps—orders and questions

To create a DRAKON diagram of a process, represent the behavior of the system as a series of orders and questions. Follow the principle: one thought—one icon. See a tutorial on drawing DRAKON flowcharts here: link.

Let's take a look at the entry point "Login with a password" from our example.

Login with a password
Login with a password

The happy path

The happy path goes down the left vertical from top to bottom:

  • Order: get the username and password from the user.
  • Order: find the user by username or email.
  • Question: was the user found? Answer: yes.
  • Order: check the password.
  • Question: did the password check succeed? Answer: yes.
  • Order: attach session to the user.
  • Order: postpone logout on timeout.
  • Order: show the personalized start page.

A less successful scenario goes to the right:

  • Question: was the user found? Answer: no.
  • Order: show an error message.
  • Order: let the user try again after three seconds.

Spare arrows for cycles

Arrows are graphical details that distract the reader and take place on the diagram. DRAKON does not need arrows for the linear flow of events. Time in DRAKON flows down. Since the direction is known, plain lines are sufficient.

Arrows in DRAKON flowcharts show cycles and do not occur often. Hence, arrows make cycles apparent.

Note that the decisions based on the existence of the user and password validity are in the top-level flowchart. Both a wrong username and an incorrect password produce the same visible response from the system: an error message, a 3-second pause, an invitation to try again.

Drop the redundant details

A DRAKON flowchart should show the actions of the system accurately and unambiguously, but without unnecessary technical details and formalisms.

In our example, the Input icon defines that the process gets data from outside—from the user.

Getting data from the user in the Input icon
Getting data from the user in the Input icon

The flowchart does not explain how the username and password widgets work, whether they show up simultaneously or one by one. The reader learns only the essence: the user inputs data into the system.

Similarly, the Output icon sends data outside of the process—an error message to the user. The font of the message text and its position on the screen are not relevant on this level of abstraction.

The Pause icon says: the process stops for three seconds, and the user cannot affect the process during that period. "Login with a password" flowchart does not define how to implement the pause. Maybe, the whole page or individual widgets will "freeze" during the pause. These technical details are not necessary to understand the functioning of the system as a whole. If needed, lower level requirements can describe such details.

Pause icon
Pause icon

Avoid variables and parameters

Programmers love variables. Programmers assign values to variables and pass variables to function arguments. Variables turn requirements into unreadable code. Variables belong to programs, not to requirements.

Avoid variables in requirements if you can. This advice also applies to passing parameters to subordinate DRAKON flowcharts.

The "Check password" procedure accepts user and password as inputs. The "Check password" flowchart shows those inputs in the Parameters icon.

Inputs in the Parameters icon
Inputs in the Parameters icon

The Insertion icon in the "Login with a password" flowchart calls the subordinate flowchart "Check password," but the icon text does not include the variables "password" and "user." The Insertion icon contains only the name of the subordinate flowchart—"Check password."

Do not pass parameters to subordinate DRAKON flowcharts
ПриDo not pass parameters to subordinate DRAKON flowcharts

If you right-click that icon, the context menu will show a link to the "Check password" diagram. DrakonHub inserted this link automatically because it found the name of that flowchart in the icon text.

The further to the right, the worse it is

Let us examine procedure "Check password." The happy path in that diagram goes straight down the left vertical, without turning:

  • Question: is the user blocked? Answer: no.
  • Question: have 3 seconds passed since the last password check? Answer: yes.
  • Question: is the password correct? Answer: yes.
  • Order: call the password check a success.

Besides the most successful scenario, there are less desirable paths in the diagram. The rule "the further to the right, the worse" prescribes to sort the paths through the flowchart. The less successful the scenario is, the further to the right it should go.

In our example, an incorrect password is worse than the correct one, and blocking the user is worse than giving him one more chance.

The further to the right, the worse it is. Example
The further to the right, the worse it is. Example

Tell your intention in orders and questions

There are neither variables nor counters for counting unsuccessful login attempts in diagram "Check password." A programmer would find it natural to create such a counter and perform the following actions on it:

  • reset the counter in the beginning;
  • compare the value of the counter with the number three when the password is incorrect;
  • increment the counter after an unsuccessful login.

Do not program in requirements, get rid of variables. Instead of juggling the values of variables, put your intention in the question or order. The intention is the desired result of the step. In our example, the intention is to detect whether the user has made three unsuccessful login attempts. The developers will find a way how to implement this intention.

See also

DRAKON Visual Language

How to make acceptance tests from a DRAKON flowchart

Learn DRAKON by Examples

DRAKON Language Reference

Video: How to draw a flowchart

Feedback: support@drakonhub.com

DRAKON Labs

Løkentoppen 21, Kolsås 1352, Norway

Telephone: +47 407 63 992

Terms of service

To the top