The importance of Technical Specifications

April 20, 2015

“Failing to plan, is planning to fail” – Alan Lakein.

I believe that no statement holds truer when taken in the context of development.  It is for this exact reason that as developers, we often dedicate entire sprints to planning and laying out required technical functionality/specifications. The technical specification is a powerful tool, its usefulness transcends merely defining scope and complexity..  I would go as far as to say, that any development requirement should be furnished with a technical specification document or breakdown, irrespective of how easy/complex it may seem. Complexity in fact, is one of the major issues that a specification document addresses; and it is through that breakdown and the creation of that technical document, that all assumptions and ambiguity are put to rest. In short, a technical specification document provides developers with clearly defined goals and direction, and ultimately allows for better management of stakeholder expectations.

What should be in a specification document?

There are no hard and fast rules to dictate what exactly should go into a specification, and what you do or how you spec out a project will certainly come down to team dynamics, resources, the size of the project, and project types. There is no real point in producing a document that could rival the Dead Sea Scrolls in density, unless you are doing some super-secret government project. That being said, there are some general guidelines that you could follow to ensure you create an effective technical specification. In this article I will outline what you would typically find in one of our specifications.

 

Language and Tone

Even at the best of times, the writing and reading of specifications can be a mind numbingly boring process. To get around this problem I often like to employ a very light/humorous language and tone.  There is just no fun in having your specification read like a lawyer’s letter, the former keeps both you and your readers engaged so that people actually want to read the specifications. For example, I often make references to classic movies, such as Star Wars when writing my user stories, as I find this makes them more engaging and less like a robot dance. I would strongly recommend taking this approach if you are fortunate enough to find yourself in a relaxed environment that allows for these types of shenanigans. You could also consider brushing up on your Shakespeare, as this might come in handy somewhere along the line.

Include a disclaimer in your introduction

I usually include a disclaimer type section in the beginning of my specification documents, as I find it is important to warn readers upfront about potential pitfalls in and around the document. This introduction section is also great for outlining who the content of the document is targeted at.

My disclaimer/introductions often read something to the effect of: “The ideas expressed in this document are by no means finalized and might be subject to drastic change”. I also like to use the section to warn readers about things like my inability to spell, just so that there is no moaning when we get around to reviewing the specification.

Section 2: Background

In this section I give a short but detailed description on why we’ve come to consider this project. This would be mainly non-technical information just to give the reader more context on the high level business requirements.

Section 3: Target Audience

While a breakdown of the target audience of a project is probably something that belongs more in a functional specification, I truly believe that you can never have too much information.  As developers we tend to easily abstract ourselves from the user and I find it is actually useful to keep the user/audience in mind at all stages of development. By including a section in the document about the target audience, we are able to ensure that a good/positive user experience is at the core of what we are trying to achieve or build. In this section you could elaborate on why this particular feature set has value to this type of audience. However, you will rarely need to go into too much detail here as the details should already been covered by a functional specification.

 

Section 4: Scope Impact

This section is particularly useful when extending existing systems. In the scope impact section we take the time to document all the possible sections of the system that this feature set could impact. This gives us developers some guidelines for regression testing later on.  A mistake that I’ve made all too often is developing and testing in isolation. Hopefully your system is not built like a house of cards in which changes in one section can take down entirely different parts of the system, but if this is the case, a scope impact becomes even more imperative as it allows you to completely understand the impact of the changes you are considering. Along with a detailed description of the impact, we will often provide an English rating relating to the feature set or project, for example: “High impacting, moderate or low impacting.”

Section 5: Glossary

Language is a critically important thing to humanity as a whole. It often surprises me how little regard we can have for it in development. This section of the specification will attempt to correct that deficit, by clearly defining all the English terms and their corresponding meanings within the context of the document and the project itself. When this section is finalized it will become the default language used to describe the business logic and entities in this feature set, so it will and should require a huge amount of negotiation with stakeholders. Getting you language right will maintain consistency from the business all the way down to a functional level. It will also help you translate complexity and requirements so that you don’t lose parties through ambiguous and needlessly complex terminology.

Section 6: Assumptions

This section is particularly useful when dealing with third parties over whom you have no control. You can often make assumptions about the operations and specifications of another system that can be highly inaccurate, more so if you dealing with a system you’ve never integrated with before.  I’ve found this to be the case with even the most well documented third party integrations. The same holds true when working on exceptionally large systems, where assumptions need to be made due to time constraints. It would be in your best interest to document these elements and the assumptions you have made regarding the system to ensure that the stakeholders are all aware of how they could potentially impact the project.

 

Section 7: Goals/Non Goals

This section is vital for preventing scope creep. In this section, you will, in no uncertain terms, document what you intend to deliver in this feature set. This is to give developers accountability for what was agreed upon and help prevent stakeholders from ‘hijacking’ requirements. It will also help to document anything that you have agreed not to deliver as part of this iteration. You may also categorize your goals into primary, secondary and tertiary objectives if the need arises.

Section 8: Implementation/Scenarios

Finally, in this section, we can outline the really technical details about the project. This section includes model/SQL/entity diagrams and details about the infrastructure design patterns and user stories.  If the project is quite big in scope, I would typically break it down into smaller feature sets and write “sub specifications” for those feature sets.

The most important part of this section in my opinion would be the user stories. We use user stories to describe our unit tests, which is why you will find them in our technical specifications as opposed to functional specifications. We use them to describe various scenarios and outcomes on the methods of our models. These user stories can sometimes make for interesting situations, mainly due to the fact that there is often no user involved on this level, but it does a great job at defining such low-level requirements.

Starting a conversation

The above is just part of our specification process. With every project that we do I am always reminded of the importance and value of these documents and the reason we take the time to create them. Over and above providing direction for a project, specifications have a very good habit of starting a conversation which typically results in more ideas coming to the table and ultimately in more refined business goals and requirements. Re-active development can really damage a team and projects, and the only way to develop a healthy development culture is through concise, deliberate and effective planning.