When to write software specifications

When it comes time to start coding a new feature for an application, developers prefer to have a very clear idea of what they need to do. The better they can understand the needs and requirements, the faster they will be able to develop, and the less likely there will be a need for re-work. However, modern software development and agile thinking also tell us that locking in detailed software specifications too early can be detrimental to the product and not in the best interests of the user. 

So when should you write detailed specifications with explicit requirement statements? Let's explore.

Why does agile discourage writing specifications too early?

An agile approach to software development means that the product is continually iterated upon and improved incrementally, rather than developed all in one block of time. This approach means you can continually gage customer needs and incorporate them into the next release. In turn, this ensures that development stays focused on the needs and wants of the users, and course corrections can be made between iterations if needed. 

If you had instead written all the specifications for the entire application before starting development, your mindset and project planning would already be locked into those plans. There would be no room to make changes and incorporate new information about the user needs as you progress. 

Agile, therefore, discourages writing all the specifications for a product before beginning it at all. 

People wrote specs for the entire app before development started!?

Yes. 

If you have come into the software industry in the last ten years or so, agile thinking and small releases or continuous improvement are likely (and hopefully) very familiar to you. However, it was not always like this.

Going back to the early 2000s when I was first working as a business analyst, writing the full specifications and all the designs was very common. Software projects were run with traditional project management approaches. This meant there had to be clear scope and deliverables, fixed budgets, and project schedules. There was certainly no room for changing the plan half-way and taking a product in another direction! 

Specs for these situations generally consisted of large Word documents that were hundreds of pages long. It wasn't uncommon to do a 6-month project of just writing specs, after which developers would come in to implement those specs - and only those specs. 

When new opportunities emerged during development, pursuing them was called 'scope creep' and was frowned upon. Project managers were not my greatest fan as I would often be in their office pleading to change the plan half-way when an opportunity to better help users emerged. To be fair, managing scope and avoiding creep was very much part of the project management frameworks they were using, and their resistance was driven only by their intention to correctly manage the project as they had been taught.

Putting it together

Trying to spec out an entire application before starting limits your success by putting you in a situation where you cannot adapt to new information and your emerging understanding of your users' needs. 

Conversely, asking developers to code a feature with only a vague description and no detail is going to mean they take much longer to come up with something, and the chances that the something falls flat and doesn't meet the need are significantly increased. You will then lose time and money re-working it.

Here's what we have found works for us:

1. Write specifications on a per-feature basis;
2. Ensure specs contain specific requirements statements before coding; and 
3. Maintain sight of the goal and always be adaptable.

Specifications on a per-feature basis

Thinking in terms of a specific feature ensures you can work with reasonably small scoped specifications. You can stay focused on exploring an idea and getting it implemented, without getting caught up in trying to write specs for every feature.

Requirements statements before coding

Before a developer starts coding a feature, the spec must have progressed to have specific requirements statements. These one-line statements set out what the feature must and must not do in as simple and absolute terms as possible. 

We use outcome-focused requirements statements. This means the statements describe what ultimately must be achieved by the feature.

They don't specify to the developer how to solve the problem from a code perspective, but act as a checklist that once passed would represent the successful implementation of the spec.

Maintain sight of the goal and stay adaptable

Keep site of the user need the drove the feature, and remember the problem you are solving for them. As you write the requirements, ask yourself, 'if these requirements are implemented, will we have solved the problem for the user?'. If the answer is no, call it out! It's ok to revisit and re-work the specs and requirements even in the development stage as new information and customer understanding come to light.

Conclusion

Software specifications with clear, specific requirements statements are a great thing for accelerating development and cutting down on re-work. However, they will limit your product's success if you try to spec the entire application before coding or getting user feedback.

Take an idea, explore it with your users until you have a deep enough understanding to write a clear specification, and then develop it! Just be flexible and ready to adapt as you learn.