Tips for Writing Software Requirements Specifications

Although I worked as a consultant for years writing software requirements specification documents to form the basis for developing different kinds of IT systems, I had never really appreciated how difficult and overwhelming most organisations see this process. It was just something that I did and took for granted.

I knew that the task was time-consuming, but having studied computer science at university, completing it has always been relatively straightforward. In a nutshell, you determine and outline the capabilities and logic wanted within the application using plain language. I'd mostly worked as a consultant for public sector or large private sector organisations, so I'd typically assumed that such companies just hadn't wanted to pull their full-time resources from their business-as-usual activities in order to get the job done. So, they found it easier to bring in and pay external consultants to do the work. Silly of me, I know, but that's really what I'd believed.

However, in September 2020, I gained a different perspective. I started Phase 1 of the New Frontiers Programme at Waterford Institute of Technology, which is geared to help start-ups develop their business model. It was then that it became readily apparent that I'd taken for granted the level of fear involved when it comes to developing and procuring IT software. Some of the programme participants were working on developing their minimum viable product (MVP), and they genuinely didn't know where to start. So, I figured, why not put in writing the process that I typically used on jobs, and since then, applied to both my Sluamor and Nohuts businesses. I'll try to limit the use of jargon, which most persons find confusing.

Guidelines for preparing the Software Requirements Specifications

Focus 1: Determine what's needed from the IT solution.

Athough I've led and otherwise assisted in the design and development of software solutions for years, it was during my time at university that I recognised the value of thinking through the solution from start to finish before writing a drop of code. I would code much faster, and with much less errors and need for re-work, after clearly thinking through and writing out how my solution needed to work. Not only does this save lots of time and money, it also reduces the likelihood of producing software products that fall short or a far cry from what you actually had in mind.

Focus 2: Write, write, write.

While thinking through what's needed for the software you want to purchase or develop, you must follow this up with good documentation. You don't want to forgot anything you've learned. That's it. Note, there's no magic bullet here.

Write the software requirements you identify as follows:

1. Prepare the functional requirements, i.e., to provide a clear picture of:
   1. The activities that the IT software is expected to support.
   2. How you expect the system to work for its end users, with other IT systems, or on its own.
2. Prepare the technical requirements, i.e., covering the non-functional specifics pertinent for the system (e.g., the level of reliability required, how data should be stored, and how user access should be managed and controlled).

Key tips to read before proceeding.

So now that we have an idea of what needs to get done, let's discuss some key tips I'd like to share with you before delving further.

Tip #1 –There's no one-size fits all template that you can use and re-use for different software requirements specifications.

It is important to understand that a solution that works for another organisation, may not work for yours, even if it is very similar to yours. Therefore, it's imperative that you clearly agree how the solution ought to work for your business, your customers and other key stakeholders (e.g., suppliers), before making any purchasing decisions.

You don't need to go in-depth. You simply need to have enough information to allow software vendors and/or developers to understand what you have in mind, especially with regards to any complexities that your software solution might entail. But, bear in mind that this recommendation comes with one caveat.

Tip #2 - Understand or remove any business process exceptions to save you money.

Dig out the details, whenever your team says something like "it's basically the same as", "except in the case of", and "99% percent of the time". Hopefully, you get the gist.

Disaster awaits if you avoid the discussion of exceptions / variances for most projects, including where technology is being implemented. If not, consider the disastrous announcement back in 2005, when trucks requiring a clearance of 4.65m (15ft 3in) or more were too high for the newly built Dublin Port Tunnel. These "supertrucks" were an exception, which caused the government to end up spending more time and money.

Exceptions are often an indication of complexities within your business processes, and when investigated on projects I've worked on, such complexities tend to occur more frequently than perceived. They typically cost money from a software perspective. So, take the time to get rid of them, unless they are an absolutely necessity. They will cost more time and money to incorporate if they're identified later on in your software implementation timeline.

Tip #3 – Involve your team.

In determining what's needed for any software application (i.e., as referenced in Step #1), you're looking at team discussions. The important thing to note is that you and your team are the key. You and your colleagues are the only ones that can complete these tasks. If you're a startup, that might just mean you're on your own, if you're the only person in the business.

Sure, you can get an experienced IT consultant on board to help you to flesh out and document the requirements, but the truth is that they can't determine your functional requirements on their own. IT Consultants will need to sit down with you and your team, along with your key stakeholders, to figure what you need for the software system.

Tip #4 – Involve key stakeholders.

Get all the different stakeholder perspectives. What do I mean by this? Involve representatives of all the different kinds of persons (e.g., Supplier, Warehouse Manager, Warehouse Operator) that will need to use the software application, or will need to get information produced by the software application. Such persons could be staff within different functional areas of your business, as well as existing or target customers.

Tip #5 – Develop the first cut of the functional requirements on your own to cut costs.

The process could take weeks and sometimes months, depending on the complexity of the application software. Therefore, if you're a small business with a limited budget, as a starting point you should save money by trying to prepare a first-cut of your functional requirements on your own. Thereafter, you can bring in relevant IT expertise to help you to fine-tune your functional requirements, to challenge the decisions you've made, introduce efficiencies that you haven't already identified on your own, and outline the technical requirements that you should include or consider. However, bear in mind that the process could take you that much longer if you do not dedicate sufficient time to getting the job done.

Tip #6 - Do relevant market research.

I never skip this step, even when we're simply introducing new features into existing software.

1. You should go online to check out software available, that can be used to do some or all of the key tasks that you need to put in place.
2. If your solution is innovative, look at IT solutions that offer features similar to the one you're hoping to implement.
3. Don't just check out one solution, look at as many as you can, until you've exhausted all the capabilities you think relevant for your solution.
4. Once you've looked at other solutions, then if you're developing your own bespoke software application, you'll be ready to visualise what you find ideal.
5. Make a list of all the features you want to incorporate into your solution as you complete the market research. These features will form the basis of your functional requirements.

Tip #7 - Keep a record of the market research completed.

Save pictures representing the system capabilities that you'd like to have in place for your solution, including any descriptions available. Get different examples of these features.

It's important to ensure that you can easily refer back to these capabilities, as and when needed, as you develop any prototypes needed for the software requirements specifications. They will prove invaluable to provide a clearer picture of your software vision, when you engage at a later date with technology consultants and software developers. They'll also work when you're trying to convince the rest of your team in purchasing pre-built solutions.

Defining your functional requirements.

The following are some guidelines to consider when defining your software functional requirements.

Step 1 - Outline your Business Processes

It is important to provide yourself and third parties (e.g., developers) with an idea of the activities to be completed with the support of the new software solution, showing:

1. The series of tasks that are to be performed to complete the activity.
2. The individuals, positions, or functional groups (i.e., the users) that will be responsible for completing each task.
3. The tasks that are to be enabled partially or fully by the application software.
4. Any information that is to be generated by the system while completing a task.
5. The different paths that will result in successful outcomes and/or any unsuccessful outcomes

Process Map Examples

The following is one of the earliest process maps that was created years ago back when our first concept of Sluamor was being fleshed out. The name Sluamor hadn't even been conceived at that stage.

Here's a more recent version, focused on how Sluamor was planned to support buying organisations in communicating their requirements to prospective suppliers.

Tip #8 - Use your market research to plan your new processes.

Continually refer back to the results of your market research to ensure that you're taking into consideration all the process efficiencies that you'd previously identified as useful or necessary for your software solution. Focus on simplifying your business tasks to removing complexities, and reduce the level of effort and time required for completion of business activities and the risk of introducing errors.

Tip #9 - Only go in-depth if needed when mapping process flows.

Keep your process maps at a high-level. They do not need to reflect a lot of detail, unless they are needed to provide better clarity for software vendors or for your team. As a result, it is imperative that you talk about the details during your discussions, e.g., to identify any process exceptions or alternative paths and outcomes. Also, it is highly likely that you'll refine the business processes before the IT system is implemented, due to decisions made during the development and implementation process. So don't waste your time providing detailed process maps until they are truly needed.

Your objective is to allow the business and implementation team to readily identify how your staff and customers should be able to interact with the application.

Step 2 - Compile your list of functional requirements.

Once you have a good sense of the tasks you want to perform using your new software, you can start to make a list of all the capabilities you need within the new IT system. These features will form the basis of your functional requirements.

For example, Sluamor's core functional requirements as we identified from early-on included the following:

1. The system is able to register new users.
2. The system is able to authenticate the email address of new users before they are allowed to sign in.
3. The system is able to allow users to reset their passwords whenever they are forgotten.

Do you see where I'm going with this? Also, you'll see that it's written in plain English, and so can easily be done and understood by anyone.

Tip #10 – Group your software requirements.

I also tend to group my requirements by key capabilities, e.g., Registration, Signing In, and Pitch Creation. It makes it easier to manage and refer to whenever needed. Your groupings will be highly dependent on your solution.

Tip #11 - Use your market research to fine-tune your list of software requirements.

Continually refer back to the results of your market research to incorporate all the capabilities you'd previously identified as useful or necessary for your software solution. In addition, you might see the need for even more features than you'd initially envisaged. If that is the case, do some more market research to see how other systems address similar capabilities. Introduce innovation, if that's important or useful for your company.

Tip #12 – Continually refine your business processes if needed.

Writing software requirements specifications is truly a cyclical process. So, always keep an eye on your business process, and refresh as needed, when you've more information at hand, e.g., from further market research. It'll never be perfect, but you don't want to overlook any step in the process, that could make the difference between a successful or unsuccessful software implementation.

Step 3 – Prioritise your requirements.

As you're compiling your list of business requirements, or when you've your first draft done, start thinking through the features that you absolutely must have in place to support your business.

You could consider the use of MoSCoW prioritisation, which translates the MoSCoW acronym to the labels: "Must", "Should", "Could", and "Wont". Alternatively, you could simply go with "Critical", "High", "Medium", and "Low". Whatever approach you use, just remember to provide clear definitions of what constitutes one priority versus another, e.g., "Should" could mean requirements that are important to the success of the project, but are not absolute musts in that there can be a workaround, or the non-provision will not cause the project to fail.

You might think prioritisation is only relevant for smaller companies with limited funds available for software purchases and development, but that's not the case. Remember, where the software solution isn't an off-the-shelf product, time could still be a key consideration for you. The quicker you can show progress, the more successful your project is perceived. So, don't underestimate the importance of prioritising.

Step 4 – Develop User Scenarios.

For developing Sluamor and Nohuts, we created user scenarios after we'd clearly identified what we wanted from the system and prepared our initial set of functional requirements. I find that user scenarios are great at reflecting exactly how users are to interact with the system. They quickly become the most referred to aspect of your functional requirements, once the developers come on board, and when you start to develop your plans for testing.

I try to develop the user scenarios going into as much detail as I can. Doing user scenarios is a very good approach for fleshing out all the specific business rules / ways of working for the planned system, that may not have been fully considered prior to that stage.

So, what are user scenarios? User scenarios visualise how system users will realistically interact with the pertinent application systems. Each user scenario is very detailed, is told from the perspective of a specific user persona (e.g., Warehouse Operator, or Website Visitor), and portrays how the application system will support the specific user persona in the completion of a specific task. They are written in plain language, to ensure that they are understood by technical and non-technical persons. See the example provided.

Tip #13 – The use of user scenarios can save you time and money.

If you don't complete this step, it's a step that you should insist that your developers complete. It would add time and money to your bill up-front, but it prevents costly mistakes towards the tail end. Also, it ensures that your company view of the how the application should work will be aligned to the approach that will be adopted by the developers.

Tip #14 – Rely on your user scenarios when testing.

Once you have user scenarios in place, your team will be able to use them as the basis for your user acceptance tests - to ensure that the developer has delivered your application system fully in line with your software requirements specification.

Tip #15 – Rely on your user scenarios when agreeing changes.

System changes are inevitable when developing new software solutions. However, you can insist on updates of your user scenarios whenever your team or your developers are discussing system changes. You want to ensure that you fully understand the extent of the changes being requested, and the impact that such changes could have on your project budget and timelines. In addition, you also want to have an up-to-date starting point for your user acceptance tests.

Step 5 – Create Prototypes.

As you complete the user scenarios, or shortly thereafter, it'll be highly invaluable to also create prototypes. Personally, I never create a prototype until after I've completed the relevant user scenario, in writing, or at times, I'll admit sheepishly, visualised in my head if I'm doing the development.

Screen prototypes visually depict how each screen / page of an application will be appear to users. You can develop different kinds of prototypes:

• Low-fidelity prototypes, otherwise known as mock-ups or wireframes.
  Low-fidelity prototypes do not allow user interactions to simulate the functionality required by the system. They can be even hand-drawn sketches, and will never visually appear exactly as you'd expect for your application. However, they should clearly outline all the different elements that should be included on each screen.
• Medium-fidelity prototypes.
  Medium-fidelity prototypes will have a closer look and feel to your expectations for the application. However, they will take a longer time to prepare.
• High-fidelity prototypes.
  High-fidelity prototypes are working prototypes, in that it they can be used simulate the functionality required by the system taking what we call the "happy path", i.e., the path expected if all goes accordingly to plan, not allowing for errors. They will typically have the same look and feel of the application being delivered.

Tip #16 – Rely on your user scenarios when prototyping.

Once you have user scenarios in place, your team will be able to use them as the basis for your user acceptance tests - to ensure that the developer has delivered your application system fully in line with your software requirements specification.

Tip #17 – Start with paper-based mock-ups.

If you're starting from scratch on any development project, use paper mock-ups as your starting point to get feedback on the screen design and content. They are easy and much less expensive to create and repeatedly refine. Once the paper versions are agreed, you can take screen shots to save for your records and/or create electronic version of your wireframes using tools such as Microsoft Word, InVision, Balsamiq, or Lucidchart.

Tip #18 – Continually refine your user scenarios if needed.

As previously mentioned, creating software requirements specifications is a cyclical process. As such, you'll not only need to refer to your user scenarios as you're developing your prototypes, but you'll also need to refine the user scenarios if needed, if your view of how the application should work alters in any way.

Tip #19 – Insist on the provision of medium-fidelity prototypes from your developers.

Whether or not you've created your own mock-ups, you should insist that your developers provide you with medium-fidelity prototypes before they start their development process for each area of your application. You'll want to sign-off on the look and feel of each screen before they get going, while ensuring that it can be used as depicted in any relevant user scenarios.

They could also opt to do high-fidelity prototypes but I typically don't bother with going down that route. However, if you've a startup looking to prepare an MVP and looking for investors, this might be a good stopping point for your organisation. You could use the high-fidelity prototypes to garner investor interest so that you can raise sufficient funds to complete the development.

Step 6 – Identify your Information Requirements.

I won't delve into any depth here, as this is an area that most non-technical persons will shy from. However, it may not be as difficult for you to appreciate, as you currently believe.

However, you should note that as you develop your functional requirements, it will be very important for you to understand your information requirements including the following:

1. The data that will be needed by the application.
   E.g., In order to sign in, Sluamor users must provide a user name and password that has already been recorded for the user by the application.
2. The data that your application will need to generate.
   E.g., Total amount to be paid for items ordered by a customer.
3. The data that the software will need to keep secured, along with the level of those restrictions (e.g., passwords must be encrypted, credit card numbers shouldn't be stored).
4. The data that the software will need to output to the system users.

There are really two main starting points, i.e., the data you need to record, along with the data you need to produce. You should flesh out the first when you prepare your user scenarios and prototypes. For the latter, you'll need to identify your reporting requirements.

Tip #20 – Determine the key performance indicators required from the system.

My approach to defining the reporting requirements of a new system varies from project to project, depending on the application. However, at minimum, you should always collate a list of the key performance indicators that the business will want from the system (e.g., total new orders, and average order age). Thereafter, you should ensure that the application will record the data it needs to generate those performance indicators, and store the pertinent data in a way that it can readily provide in any reports to be created, or to any data warehousing solution that your organisation relies on.

Tip #21 – Create Mockups of Reports.

If you're replacing an existing system, collate the different reports, dashboards, charts, letters, emails, or other outputs that the business relies on, and use this as your starting point. Keep them in a repository.

Do a mockup of any new reports, dashboards, charts, letters, emails, or other outputs that you will need outlining details such as:

1. Why the report is needed (e.g., to show all new daily customers orders).
2. The title of the report.
3. The data to be shown in the report (e.g., the reporting date, the name of each item purchased along with the item number, volume purchased, and its net and gross sale prices grouped by the customer id and the customer name), the rules for generating any data to be shown (e.g., for calculating the gross sale price for each item, each customer and for all orders for the day).
4. The different ways in which the report could be sorted or filtered.
5. How often the report will be generated.
6. How the report should be generated (e.g., manually and/or automated) and delivered (e.g., via email, PDF, Excel, and/or printed).
7. Any drill-down capabilities required.

At some stage, you'll also need to discuss the branding and expected appearance of the report, but similar to the approach with prototypes, start with paper-based mockups before doing electronic versions.

Tip #22 – Continually refine your business processes if needed.

Refer to your business process diagrams as you identify your reporting requirements, and likewise, refine the process maps as needed, if you'd like to reflect any additional outputs that ought to be generated when users are completing key tasks. Remember these outputs do not need to be only reports.

Tip #23 – Obtain data models from your developers where relevant.

Technical teams will prepare what is referred to as data models as part of their design process, and doing this will be difficult for most non-technical persons. However, the data models can be presented in a way that is readily understandable by your team regardless of their technical capabilities. Ensure that this is the case.

Note, data models are not needed for developments where there is little or no recording of user data, as is the case of websites with mostly static pages (e.g., where there is only one form on the Contact Page to receive request for assistance).

Your data / information models should visually depict the data to be stored in the application outlining the following:

1. Entities.
   The different kinds of data to be stored (e.g., customers, products, and orders).
2. Entity relationships.
   Any relations that are required between entities (e.g., an order is created for a customer, an order is must pertain to a product).

A description of the entities shown also be provided.

Tip #24 – Obtain data dictionaries from your developers where relevant.

Used in combination, data models and data dictionaries will give you and your team the ability to validate that you'll be storing all the data that needs to be stored within your application, so that information needed by your users or other stakeholders can be readily obtained in a straight-forward manner. So, I personally believe that they are a must. However, this is something that a lot of businesses, large or small, do not insist on as part of their endeavour to save costs. However, what can ultimately happen years later when you want to move away from the application developer, is that they hold your own data as a hostage against you, when you're looking to change systems. I won't add how detrimental this becomes for some organisations, as I'm sure you can imagine that on your own.

Data dictionaries should outline the following:

• All the fields / attributes that comprise the different entities.
  E.g., a customer record should contain a customer identifier, an email for the customer, the name of the customer, the data on which the customer was added, and the date on which the customer last signed in.
• The values that can be accepted for each field when storing the data.
  E.g., a customer email is required for the customer entity and must be a valid email address no longer than 255 characters long, and the date on which the customer was last signed in is not always required, but must be a valid date set to the date on which the customer record is updated and no longer than 10 characters long.

Tip #25 – Flesh out your data entry and validation requirements when creating your user scenarios.

As part of my process in developing user scenarios, I'll often start to think about the data that the user will be required to enter into the application while completing their task, as well as how the application software should prevent invalid data from being accepted. As such, I would typically include these details in my user scenarios, so that they can easily be pulled out when we're ready for prototyping, visualising the data model, determine the business rules for data validation and data storage, and ultimately when carrying out testing.

Defining your technical requirements.

From time to time as you complete your research, you'll also identify technical / non-functional requirements. Writing technical requirements is somewhat like preparing a list of service levels you'd expect from a supplier, except in this instance you're looking at the mandatory level of support you'd expect from the application to ensure that it provides a quality service to all users without causing any reliability, availability, security, scalability, maintenance or performance issues.

Examples of some of technical requirements include the following:

1. The system will provide audit trails.
2. The system will encrypt all user passwords.
3. The system will facilitate the management of users accounts via an effective user administration facility.
4. The system will be available 99.99% of the time for any 24-hour period.
5. The system will be easily upgradeable in that fixes and/or upgrades can be applied in less than 1 hour.

That's it. Get in touch if needed.

I certainly hope that you've found the above helpful. Feel free to get in touch if you'd like me to provide further guidance or if you have any queries.