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.
Latest comments (2)
but here is the thing, often customers just can not imagine a solution. hammering into the keyboard and crank out a prototype can be very cheap too.
That is where agile and scrum kick it. take the client with you on the journey.
at some point you have to get going. and in the before the project starts you AND the customer know the least about what is really needed.
When the planning phase is eating up much of the budget the project has little room to pivid.
how do you keep the balance?
thanks for the comment and i see your point.
the tension between planning, documentation and coding is extremely difficult.
however, i think that we in the software industry are often too far on the coding side.
if you know what I mean
i see many projects, especially in the ERP environment, fail because no one has thought about it and just start working.
i know that customers often don't know what they want, but as software developers we have to work with the customer and elicit their wishes.
sure, if the customer wants a bridge over a small river, you can quickly put it together with a few planks. But if the customer suddenly drives over it with his truck and it collapses, how are you going to prove that it was only a proto-type or only for small loads?
in court, you would want to have a document that says the bridge is for pedestrians only.
you can also build prototypes during the planning phase, but only to see if something works. to collect data. but in my opinion it is better to build a piece of real software to collect real data.
then you can extrapolate.
this is also true in agile. here you just divide the steps into sprints and don't do the planning from the beginning. but even in agile you need contracts and documents and planning.
in the backlog you also have the individual requirements, which you fill with life in the course of the sprints.
and right, of course it all depends on the project size. if you have a 100$ project, you won't have a budget for planning. the question is if it's a real project then.
only my 2 ¢
as with coding, we also work with building blocks in the specifications. this gives us a basis.
so if someone wants a print function, for example, then we either already have a specification for it. If we have never done this before, we look for similar requirements. There are already all the assumptions that are usually given to such a function described. if the customer finds this good, we can implement it.
or he enters the discussion and brings in his requirements.
i think you can talk a lot about the project, but it's not real until it's black and white.