Table of contents
Software engineering - is specification important?
The content here is under the Attribution 4.0 International (CC BY 4.0) license
Recently during my daily work, I started to think about software specifications. The development world is living in the agile era and is even more aggressive with deadlines and quality.
There are two extreme scenarios we can begin with. The first is a team where developers don’t have documentation at all. The second is poor documentation, which means that developers usually have something to guide them when coding, but many questions appear during the development process.
The best scenario is obviously to have a great document with all the details needed and no change requests from our customers. This is impossible to achieve. Requirements lead to the necessity of the software. Does your client understand that? Programmers often hear “But it is simple, you can do it in 5 minutes”.
Understanding the requirements of a problem is among the most difficult tasks that face a software engineer.
Software Engineering: A Practitioner’s Approach - Pressman Roger S. Pressman p. 119, Chapter 5
The client is used to his business rules and his needs. He deals with them daily and probably teaches others as well. Software is made to solve common problems. It turns into a problem when the client doesn’t understand it, and it is not hard to see documentation written like “this page is going to show the list of users”. Step back for one minute. Can you see anything wrong? I can imagine at least the following questions:
- What kind of users?
- What are the needed fields to show?
- Should we paginate the results? If yes, how many users should we display by default, maybe 10? 20?
Programmers also have their share of responsibility in this. Usually, the normal approach is to jump right into the code before fully understanding the problem.
Designing and building computer software is challenging, creative, and just plain fun. In fact, building software is so compelling that many software developers want to jump right in before they have a clear understanding of what is needed.
Software Engineering: A Practitioner’s Approach - Pressman Roger S. Pressman p. 120, Chapter 5
In the end, this process becomes a cycle without an end. Wrong documentation leads to a wrong implementation, which makes customers unhappy.
Thinking in long term
In the end, the solution seems to be easy, isn’t it? To fix the documentation problem we could add one more step before implementing the code. The flow would be to create the specification, read it, understand and remove possible gaps, and after that, start the coding.
This approach works fine when there is time to implement and do everything as planned and you have the customer working with you. The downside is when the customer tries to work around the flow, adding pressure to the delivery of what hasn’t been documented, and the lack of technical understanding can lead to even worse pressure. (In the end, everything is fast and easy to implement, right?)
Working software over comprehensive documentation
Working software over comprehensive documentation - Agile manifesto
Nowadays, the agile term is understood and spread by many professionals on the market, avoiding the real needs behind building real software.
Working software is always preferred over documentation. In the end, we are programmers and we love code, but things start to become more complicated when we have the following items to deal with, which start to bring no value to the customer:
- Working remotely
- To work on software over documentation, the prerequisite is to have the customer you’re working for always available. Otherwise, there is no meaning to start coding. How will you ask possible questions?
- A client without technical knowledge
- Following development without any flow gives the customer the wrong feeling that the software is built as they want it.
- Different languages
- Documentation is the bridge between the customer and the real implementation. It is easier to change something in the earlier stages.
In the end, the money is the ruler
I’ve seen the best professionals in the market get fired even when following the best practices. Even more, the startup wave is bringing a new concept of software, where fast and working is what matters. All in all, I believe it is a matter of thinking carefully about each aspect when building software, from the documentation to the final user.