In the beginning, the programmer created ...

I have often observed that not only newcomers and founders want to start programming immediately, but even seasoned professionals neglect the planning of their projects.

As a developer, you actually would like to hit the keys immediately and start the first executable prototype. And that's understandable. That's why you became a software developer and not a writer.

That's OK for private projects, but at the latest as soon as you want to earn money with your work, that's the end. If you don't know the requirements of your customers and document them precisely, you will pay dearly when it comes to acceptance.

Another problem is that very few customers have an idea of their problem, and there are rarely any specifications.

Therefore, the first step is to put the customer's requirements in your words and put them on paper. This starts with simple questions.

What should the software do?

Who should use the software?

All the way to concrete requirements: Should there be a print function.

There are many great software products for documenting requirements. But often these solutions are designed for large teams and are often difficult to maintain.

You can of course use word or libreoffice and that's ok.

We therefore decided to write our requirements in simple plain text files as prose. So, simply open a text file and document the client's requirements.

Each requirement goes into its file.

We use Markdown to create a PDF later.

After we have documented all the requirements together with the client, we have the document approved.

This gives us and the client a good working basis.

Simply put what the customer wants on paper. As continuous text, sketches or some form of diagram.

That's it.

Part two

That's how it started, and the story could end here.

But we are software developers, and what can we say, we like writing software. So, it didn't take long until we had a little tool that helps us with recurring tasks.

Let the music begin.

We put the small tool into the world so that they shine across the world. We call the tool reqman.

Back to reality.

It is not a giant tool but rather a small helper, but it has its justification.

So, what can the tool do?

Small things.

Create a new requirement

The following command can be used to create a new request.

reqman requirements add --id 1425

All this for the creation of a text file? Well. We quickly realized that we needed some structured data and inserted a YAML block at the beginning of each file.

So, this command inserts a template.

Display all requirements in one table

reqman requirements print -c ID -c Estimation -c TimeSpent

The following command can be used to output the requirements.

| ID   | Estimation | TIMESPENT |
|------|------------|-----------|
| 1426 |         8  | 0h30m     |
| 1425 |         8  | 0h30m     |

The columns can be defined thanks to the parameter --column or -c.

Some statistics

With the command report, a few values can be calculated. For example, the standard deviation of the required times relating to the estimate.

reqman requirements report

The result will be ...

## Listing

| KEY | PLANNED VALUE | EXPENSE | RATIO |
|------|----------|-------------|-------|
| 1425 | 8        | 4h30m0s     | 56.25 |
| 1426 | 8        | 6h0m0s      | 75.00 |

## Statistics

| PLANNED VALUE | EFFORT | MEAN | VARIANCE | STANDARD DEVIATION |
|---------------|--------|------|----------|-------------------------|
| 8             | 10h30  | 5.50 | 0.25     |            
     0.50 |

More commands

We have implemented some other commands. One of them is to output a change history.

reqman changelog print

The command item outputs the required items, and privacy outputs a data protection overview. With task, all to-dos defined in the document can be output as a table.

The grand finale

With the overview command, we can create a single text file or PDF from the individual files.

The developers of Pandoc and LaTeX are the shoulders on which we stand and to whom we owe the final document.

Connect to Gitlab

In the latest version, data from Gitlab can be integrated.

Credits

We can use it to quickly write our requirements in our preferred editor, and we end up with a nice PDF for the client.

But the most important thing is that the individual documents are still simple text files that can be easily edited with any tool and versioned perfectly with git.

What is the lesson?

It doesn't always have an expensive tool. I would say take simple techniques, build your own little helpers and create your own ecosystem that meets your needs.

Then even such a task as documenting requirements does not cause much stress anymore

And have fun.