Many developers create an idea in their mind and just start working on the delopment of it. I used to be like that myself. They let all pieces come together as the process flows and find creative solutions to problems when they present themselves. That’s good, because basically most of the available time is spent on actually coding the application.
But it’s also bad because it increases the risk of having to start over half way the project because not enough thought went into the application architecture. Features and goals are easily miscommunicated to stakeholders and developers and after a while it becomes unclear which things were agreed on and the project tends to create a life for its own.
Obviously, working on an application with a team in a corporate environment and with a lot of stakeholders and with lot of money involved, it’s important to have a clear software requirements specification, or SRS for short.
In this article, I outline some basics about writing a solid SRS and present some best practice methods from my own personal experience.
What is written in a good specification and why it is important
A good spec contains an extensive description of what the software does and why that functionality is needed and who the stakeholders are. This is important because it presents a central guideline and a vision for the team. Everyone knows what needs to be done, why and by when.
The spec also contains proposed performance metrics related to speed, availability, maintainability, recovery time, response time and so on. This is necessary to push the quality level of the delivered work to the next level.
It’s also important to define how the application will interact with other existing systems if applicable. This is where API specs come in and give an overview of where each logical part is situated.
Next to that, the spec should contain other non-functional requirements, such as compliance and quality standards, but also any design constraints. That’s needed for extra costs and risk calculation.
In the light of creating an experience for the end user of the application, some use cases should be worked out of how users will use the software. This helps the team to put itself in the user’s shoes and create every aspect of the application with the end user in mind.
The added value of a good spec
It’s takes time and effort to write a good specification. All of the stakeholders should be interviewed and a lot of calculations should be made for costs and risks. But a well written SRS makes the difference when executing the project.
It provides an accurate description of the tasks and tests to be executed and the scope of the project. These tasks can be created in a SCRUM planning tool for example and provide easy to manage tasks with details for designers, developers, testers and system administrators. Your SRS needs to contain all information for the development and design teams to build the product.
The spec also aligns customer requirements with proposed features, which is absolutely necessary to avoid though discussions with stakeholders afterwards.
Having all project information in a central place makes it manageable and updatable in an efficient way at any time. The input coming from different stakeholders is combined in a single document, which makes it manageable. It provides a single reference for customers too.
Furthermore, a good spec makes communication about requirements easier, reducing development time and costs.
Best practices to get you going
Be a thinker. Make sure to spend a lot of time thinking about whether each feature meets customer requirements and use measurable elements to do so.
Be clear. Make sure only one interpretation exists for your feature descriptions and make them extensive, adding details for performance, design constraints, integrations and so on. Also, add graphics because the goal of the SRS is unambiguous communication and putting information into a scheme or an infographic can go a long way in making the stakeholders understand what you want to bring across.
Be prioritizing. When describing features, rank them in order of impact and importance in order to make a reliable risk calculation and plan for stable software. This way, development choices can be traced back to their origin and when the planning gets disrupted, it’s a lot clearer which decisions to make when repairing damage.
Be lean. Make sure the solution’s features are designed in a way that they are maintainable and allow for easy modification. The application and its features should be easily adaptable by the customer.
Be smart. Write development goals that are SMART. They must be Specific: who, what and when, where and why is this feature needed? They must also be Measurable: how much of what until when? Set milestones and metrics. You also want your goals to be Achievable: are the tools and skills available to you when making promises? Goals must also be Relevant: while prioritizing, be sure to make a difference between core-features and nice to haves, together with your stakeholders of course. Finally, goals should be Time bound: set milestones for iterations and deadlines. This helps making things more tangible and motivates all involved parties in taking action.
Be relevant. It’s easy to document every single detail, but especially when reinventing the weel, try to be brief. SRS documents tend to become large quickly, loosing their accessibility by doing so.
Be communicative. All communication in the SRS must be written in clear and understandable language to avoid any miscommunication, possibly leading to great consequences. If you are a developer, involving someone with great technical writing skills is mandatory. They are more skilled in writing and clear communication than developers usually are, which is OK; devs are better at something else. Also, it’s important to write the specification for your target audience and use the correct way of writing things.
Be structured. When it comes to writing documents, it is helpful to start with an outline of all things you want to write about. Therefore, start with a skeleton document. There are many templates available online and there are many good ways of structuring your document, but below are two examples of a good document flow.
Structure A
- Introduction
- General Description
- Specific Requirements
- Supporting Information
Structure B
- Purpose
- Scope
- System Overview
- References
- Definitions
- Use Cases
- Functional Requirements
- Non Functional Requirements
In the document sections described above, goals and activities should be described as listed below:
Be an interviewer. Sit together with all stakeholders and ask the right questions. Be skeptical and double validate the claims by all contributing parties. Here some helpful questions to ask.
- What problems that you face today cannot be solved with your current systems?
- What problems do you want to solve with the new software?
- What processes do you want to automate of make better?
- What data do you want to get manage and get out of it?
- What elements will make the software successful for your organization?
- What does a feature that solves this problem you speak of look like?
- Who will use the software and who will use which feature?
- How will we know when this feature is completed?
Some pro tips to round up
- Share a central web hosted version of your SRS to ensure all involved parties are looking at the same version of the document at all times. Plans and specs are always subject to change and a lean way of work is encouraged.
- When integrating with legacy systems, spend enough time evaluating any constraints and elements to be adapted. Calculate the impact it will have and double that in order to foresee the unforeseen.
- Spend A LOT of time thinking about and rethinking your solution for complex problems. Use your network to challenge you on your solutions and consider second opinions. You are never alone on this world and people appreciate it when you are able to put your ego aside. It’s no use being an arrogant fuck.
- Don’t be afraid to change the specs based on new information. It’s beter having to rework features than to deliver crap. We work in IT and must be willing to press the delete key and learn something from a flawed spec. Have the courage to admit a mistake to yourself at least and rewrite a feature. Embrace change: we don’t live in the ’90 anymore.
Sources
- https://www.onedesk.com/writing-a-software-requirements-specification-document
- https://www.smartsheet.com/software-requirements-specification-101
- https://www.smartsheet.com/how-write-smart-project-objective
Feel free to leave a comment below. I love to be challenged and look forward to your contribution.
Cheers!
Thomas