Software as specification

In my 20+ years of career, I did work with many companies, and almost everyone had different ways to handle specifications.

I did work in huge waterfall environments that had more than 3000 pages of specifications for projects with five years of planning. The specification did not change even if they were completely wrong in some cases. But, we can say that the specification was needed there. It might be because one system has to interact with 20 other systems in a time challenging environment (embedded systems). The whole thing was slow and felt heavy. The meetings were endless, and deliveries were highly celebrated. Maybe I’ll tell more about it in another post.

Other environments had no specification, and what to do was dictated by a person that changed opinion every day (yes, it was a mess). Uncertainty was the norm, and work came on strides. Frustration was floating in the air, and motivation was low. I prefer not to remember more about this. To be honest, I am still trying to forget it.

I did also work in deep agile environments. Everything was looked at through the agile glasses, and people were trained on the manifesto. There I learned a way to manage specifications that I found the most compelling when we are talking about software development.

I would like to tell you how it works in this text, but first, I need to explain the specifications’ problems.

Disclaimer: I do not consider myself an expert on agile. It is just that I have worked and studied many processes, and what I explain here is based on that experience intertwined with my opinion on the topic.

The Problem

I will tell you an anecdote first. I remember that sometime in early 2000, BMW sent us the specification of a new product in German. They came with an English version, but their statement was: “If there is any discrepancy, the German version is the valid one.” But, we only had one person in the team that was “fluent” in German! That was unsettling indeed.

In general, the specification is a document or set of documents that describe the behaviour of a software system. Usually, they are precise on what the software should do, and in some cases, it also specifies how it should look. It might contain information like the format of the texts, disposition on screen, the behaviour on resizing, etc. You get the picture. Most of the time, they are incomplete, and there is negotiation during the implementation, which is normal and okay.

We do not want to confuse documentation and specification. I see the former as a result of the work of the team. It is built for the end-user or for other teams using the interface of your system. But that document does not describe how it behaves unless It is a small system; rather, it explains how to use it.

Imagine a team formed by 6 people, like 3 developers, 1 tester, 1 designer and a project owner (PO). I disagree with that kind of team disposition, but I’ve often seen it, so I take it as an example.

Imagine also that they get the specification externally o it is created by the PO. The end result is the same, they have a textual specification to work with.

It is often the case that the specification is incomplete, so we update the document as we find gaps during the implementation. Usually, the PO is responsible for making those changes and keeping the specification up to date with the implementation.

But, we are humans, and we make mistakes so, the PO forgets to update some requested changes. Or the designer, that is also responsible for the UX, agreed on some changes with the developer but did not inform the PO about it. It will also happen that the PO was not available, and the developer took some decisions that forgot to tell the PO later. I’m sure you can also imagine similar scenarios. How long do you think the specification will be in sync with the implementation?

In that scenario, which is the source of truth? In other words, what is the right specification? The document or the software?. How long will it take for the software to behave differently in different places (inconsistency) due to inconsistencies between documentation and application? As I have seen, not too long ago.

We could well reach the point where we can trust neither the specification nor the software to be correct.

When somebody sees a discrepancy between software and specification, that person doesn’t know which one is correct.

Usually, we think that the documentation is the source of truth, but rarely the discussions are taken in front of the documentation. Instead, we discuss in front of the software, and later the documentation has to be updated accordingly.

But we can elaborate a bit more. Now the company grows, and the team is now bigger. Let’s say 10 developers, with 3 testers and 2 PO’s (I have seen that as well). With that, the specification grows a lot, and you have to maintain it and keep it in sync with the implementation. It looks like now we have two projects, one building the software and another building and keeping the specification updated.

Not having a single source of truth is a bad idea.

The bigger the project and the team, the bigger the specification maintainability problem.

Exceptions

I’m not saying that specification is a problem always. Some projects will need it, especially those that the customer is giving or requesting the specification. In embedded systems, the specification clarifies how the software should behave with time, temperature, hardware, and other restrictions. This approach will apply to many other distributed systems as well.

Instead, I’m saying that not all systems need the same tools, and specification is not the same for all types of applications.

But again, do not confuse specification with documentation. The latter will be needed for those systems that need to be used by other systems or the end-user. For example, the user of a complex drawing application will benefit from having a nice set of documentation to learn to use the software efficiently.

One Solution

A word of warning. I did explain things here in a silly way like you didn’t know all this already. But bear with me. I did it that way to try to convey my point more clearly. Also, I selected a small team in my example before because this solution will work better there. But, it might not be possible for bigger teams with more “formalism”.

Do you remember the agile manifesto?

“Working software OVER comprehensive documentation.”

That can be understood in different ways, of course. But, in my opinion, it also applies to the scenario that I presented here.

The goal is that we want a single source of truth that is the closest possible to what we designed initially and that contains all the decisions taken along the way.

Step 1: User Story

First, let’s divide the specification into small chunks called User Stories. Those chunks are small enough to be implemented, tested and approved quickly (within a Sprint).

As you will see later, the words “tested” and “approved” are paramount here.

Those user stories roughly contain:

• Rationale or context
• Requirements (can be included in the AC)
• Acceptance Criteria (AC)
• Test point of attention (TPOA)

And will also contain all the discussions that will happen during the development phase. The User Stories are negotiated, modified and adapted during the development to ensure that the result is what we want.

We should think of this as the small roadmap the whole team works with to achieve the desired result. Notice that the complete team design, discuss and develop over the same micro document.

Step 2: Implementation

By whatever the process, SCRUM, KANBAN or any other of the flavour of agile, the user story will be implemented, negotiated, adjusted, tested, and retested. But before we are done with it, let’s secure those changes by adding tests covering all acceptance criteria. This has two main goals at this moment:

• All the acceptance criteria are implemented and match the initial request and any other decision taken during possible negotiations.
• Ensure that coming user stories won’t affect (break) the previously approved acceptance criteria. Reduce regressions.

Note here that changes should be tested on the final product, not only on the development branch, but I won’t enter here into details of the whole process.

During the development, the user story is the law. QA will be testing constantly that all the AC’s are covered accordingly, including all the decisions taken during the development itself.

Step 3: Done, for real.

And finally, those changes are Approved.

At this point, the work with that chunk of the specification is DONE. It is imperative to notice that all acceptance criteria have been verified, secured, and approved.

So, the software contains the specifications. You might say that it has bugs, but we did our best to minimize that with the verification and the test. Also, we should admit that textual specifications are often incomplete or contain inconsistencies (let’s call those: text bugs).

Then, if the software contains the specification, we can say that the software is the specification now. Great, now we can ditch the text.

Step 4: Archive the old specification, long live the new specification!

Wait, what? Is the specification the software? YES.

You can go ahead and think about the text specification as deprecated, and now you can safely archive it for history. We will never look back at it, so you can also throw it away.

From now on, your specification is alive and working. You can verify it anytime you want and even stress testing to identify hidden problems. Try to do that with the text if you dare!

By embracing the software as the specification, you will get the following direct benefits:

• No textual specification is to maintain.
• No inconsistency between software and specification because the latter does not exist.
• You never look to the past (old specification); instead, you look at the current implementation and the future.

In general, I noticed more respect for the software itself with this approach. It is like people treat it more seriously. I know that it sounds weird, but that is what I experienced.

Conclusion

Agile is all about simplicity and a focused process. Getting rid of overhead on your development process is vital to making your team focus on the right target.

I did decide to explain my experience here because It might help you identify improvement areas in your process.

Let me finish with another anecdote: When I was working on using this process with an extensive photo editing application, there was an after-work to build the User Manual. Because we do not have specifications, there was no direct source but the software itself. So, to create the User Manual, the PO had the list of features implemented, and he was doing live demos to the creators of the manual. After that, they could play with the software to polish the user manual at their will.

Thank you to the fantastic team at DxO for teaching me so much about agile: Fred Leboucher, Jerome Duquenoy, Patrice Lanice, Ludivico Giammarino, Alex Nazarenko, Christophe Martinaud and Gregory Fontaine.