Human-friendly specifications are the key to better software

Dear business leader,

Are you tired of listening to excuses from the IT or R&D department like “something came up” and “this was unexpected” on the day you were expecting to see an IT system or end-user-service?

What happened? Is the delivery organization yelling at you that your requirements were not adequate, even though you got the end-customer involved in the planning phase?

What if you could find the root cause of all of these problems?

We all want to make valuable software for human users in a world riddled with error-prone processes, expert biases, and organizational struggles. My colleague Tatu wrote a very nice introduction to ATDD and TDD describing what it is and how it helps an organization “shift left”.

Let’s dive deeper into the problems of planning too late and not linking your business requirements (specifications) to the Definition of Done.

Definition of Done is the driving force of Agile

Even with Agile methodologies, focusing on real customer value can be extremely hard.

When software organizations (business and IT/R&D) begin their agile transformation and starts to truly be agile, a very common problem is the ambiguity of the term Definition of Done (DoD) regarding the end user requirement. In other words: how do you ensure you’re doing the right thing from a requirements point-of-view?

A low-quality DoD can be the symptom of many problems. Usually, it means that you don’t have a good way of honing down your acceptance criteria for the end user.

I would say that if your UX designers, developers, ops guys, and testers start arguing about the correctness of the features in the demo meeting, you have a lot of unnecessary code and technical debt in your software development process. This debt is commonly referred to as “waste” in your software project.

A demo meeting should be used as a review step to check the DoD of your work items. It also gives you the opportunity to show the deliverable to end-users to get feedback for upcoming sprints.

Planning is dead, but it isn’t

As a developer and automated test engineer, I have experienced agile transformations the hard way. After the agile evangelists “left the building” and said that there is “no technical and specification oriented pre-planning” (we’ve all heard that before...), you are left kind of helpless. How do you focus your daily activities and communicate clearly about what needs to be done from a business point-of-view to get the features and epics to demo shape?

And remember: a User Story is not a specification!

The problems are even more evident when you are trying to push the actual release out. Communications start revolving around end-to-end use cases when you should be finalizing your release, and at this point, these considerations are usually too late.

Communication, of course, is easier when you have less than twenty people working on your end user service/product (all stakeholders included). But if you have more people, let me tell you, more is not merrier.

Without a clear vision (end-user DoD) for your agile method (scrum or kanban), you don’t have the focus you need for your development. What’s more, your teams are missing a clear direction.

The mess of not having a clear system-wide goal

If this looks familiar, chances are there’s room for improvement in how you’re planning. Insufficient specifications and not having the right tools for verifying those specifications in an agile way (meaning no business level/end-user oriented test automation) are hampering you when, these days, they no longer should.

Let me labor the point. If your planning is a mess, you allow people to assume things and that’s risky, to say the least. Technical issues are not usually the problem: the business requirement and the testing of those requirements are.

A clear indication that you are doing “mini-waterfall” or “Scrum, But” is that implementation and testing is done in different sprints, without clear functional specifications beyond bullet points on a word document.

Nobody wants the waste and technical debt this causes. You can run your project like this for a certain time, but making additional changes on top is going to create an unusable and an unworkable system at the end of the day.

Because DevOps loves to remove waste

One theme that comes up again and again in DevOps literature is the removal of waste. Doing the completely wrong thing is the biggest creator of waste and in nobody’s best interest!

So, in the case of bad planning, what you need is methods and tools for validating the end user value, and make the testing of those values as fast as possible.

Specification by example with Gherkin and Robot Framework

If SW engineers don’t put enough effort into their specification work, the end result is a huge amount of wasted time and money.

You need specifications, even in the agile world! But here comes the important part: you must create them so that a human can understand them. Because translating technical specifications to end users and collaborating with them is at the core of Agile methodologies. Especially in large and complex organizations, where not everybody is a software engineer.

Attaining a clear understanding of the problem and a solution for it is possible using Specification By Example (SBE).

1. Combine SBE and Design Thinking to explore and select a good solution for the verified business problem.
2. As a result, you will have end-user behavior documented (start with a couple of “sunny cases” first) in Gherkin syntax format (Given, When, Then).
3. After workshopping on those Gherkin format use cases, you have a clear user flow to implement and to test.

Next comes the power and beauty of a keyword-driven test framework, like Robot Framework. You can actually implement the automation under those steps which leaves you with a system-wide E2E test case which is, happily, your business requirement specification!

Now you have Acceptance Test Driven Development in use (picture 2)! This not only benefits testing and QA people: the whole project now has a clear goal to pursue.

With common understanding comes efficiency and focus for the development flow.

A clear Definition of Done brings focus

In my experience, when you handle your functional and technical specification like this, the actual sprint planning and execution could not go smoother!

Especially during the sprint, the peace and focus that achieving a DoD before the Demo/Review is finally possible. To make this workflow possible for your team, a huge amount of discipline from every stakeholder is needed (yes, especially from the Business Owner and Product Owners). Training is needed for all the parties involved. Especially in the beginning, the stakeholders should hold the first workshops face-to-face.

As always, we are here to help. Drop us a line if you need any help removing your waste.