Latest posts by techwriter (see all)
- How NOT to Look for a Writing Job (1) - January 22, 2017
- Hazards of Poorly Written Technical Documentation - December 26, 2016
- Get an ‘A’ on Your Next Research Paper With These 6 Simple Steps - November 28, 2016
By Tia Peterson
SRS stands for Software Requirements Specification and among other things, it serves as the end all be all of a forthcoming software product. When written well, it clearly defines the “what” of a software product – what does this thing do? It is not supposed to talk about the how – that is defined elsewhere. Neither should it discuss the why – that should have already defined in a vision or project scope document.
When I think of the term SRS, images of thick, heavy binders full of double-sided paper fill my head. So do tired printers, overflowing recycling bins, expensive ink cartridges and filing cabinets filled to the brim with documents that are never read. The tragic life of an SRS usually ends either forgotten on an ex-employee’s dusty desk, or in the recycling bin (which is, at least, a far more graceful ending).
SRS = Obsolete
Solid, well-communicated requirements will always be crucial to any software development project, no matter how agile the process is. But SRS’s are the house those requirements dwell in, and as we become far more focused on efficiency over elegance, the SRS is now a thing of the past. Here’s why: Formality is a swear word right now in the industry. Not just in the way we all wear jeans to work these days. Formality is viewed really negatively – and with good reason. Formality should never become more important than efficiency and too many times that is exactly what happens when it’s given even an inch of space in a software development project. The answer is to throw out the rules (or most of them) and create something that works. If the documentation looks pretty but doesn’t communicate effectively, you’ve just lost to formality.
I should note now that there is a difference between documenting business requirements (for the benefit of the customer) and documenting functional requirements (for the benefit of the developers and testers). This article focuses on the latter – the functional requirements.
So how do you get by without an SRS? By focusing on function, rather than formality. Find a way to get out of the “requirements must always be written in a spec” box. Let’s take a look at the use of functional requirements, as this may help in understanding this point: functional requirements tell a developer what the system or process must do. That’s it. Yes, some teams use functional requirements in additional ways, but I am not advocating those additional usages. So, since functional requirements simply tell a developer what the system or process must do, perhaps the way in which these requirements are documented can be a bit more flexible? I’ve seen requirements listed in an Excel spreadsheet, in a PowerPoint presentation, and delivered orally in a meeting where it was up to the developers to take good notes their own way. I’ve seen them modified as a result of back and forth e-mail exchanges or telephone conversations and I’ve seen them drawn in pictures on whiteboards. Look for ways that work with your team and modify your process accordingly.
The important thing is that the requirements get communicated and communicated well. An SRS is not an automatic prescription for well-communicated requirements. It’s a template – and like all templates, they have their limitations and constantly need to be modified. But why spend time constantly modifying the template, when you could be spending that time perfecting the requirements themselves?
Know Your Team
Some developers need a spec and won’t work without one. That’s OK – because this article is not advocating ditching documentation altogether. Documentation is good, and inevitable – it will surface whether you like it or not! It’s a natural, necessary part of the development process. That said, a spec can take on many formats. Get to know your team so that you know what they need to do their jobs well. One developer may follow your spec to a tee while another may simply e-mail you with question about the functionality (thus keeping a much needed paper trail). You will want to find the most efficient way to communicate the requirements to everyone on the team.
If you maintain a running list of functional requirements (e.g., in a spreadsheet) you will be able to deliver them to the developer who requires the spec, while also being able to reference them when speaking to the developer who would prefer to e-mail or talk openly about them.
Break Them Into Manageable Chunks If your SRS is six or seven hundred pages long, it’s too long. You need to trim the fat. It’s easier to trim the fat when you break the document into manageable sections. No one is going to read through several hundred pages of documentation, and if your reasoning is “well, at least it’s all in one place” you are prioritizing formality over function again. It doesn’t matter that it’s all in one place. What matters is that the developers who need the requirements can find them quickly and easily and not be overwhelmed by them.
If you are writing real, efficient requirements that talk only about the what (and not the how, remember) your spec should be clean and easily understood. It should also be rather simple in appearance. Lastly, it should be organized into sections that make sense. Try to create a story of the user and talk about the functional requirements using that story. Break up the document into the most logical “things” the user is doing with the system or process.
Adapt Easily to Changes
One of the problems with formal requirements documentation is that the change process is also formal. The problem with that is that new formal processes are required to manage these change processes. It’s an endless cycle of formality.
Keeping time management and budget in mind, come up with ways to alter requirements as necessary, particularly when the source of the change request is the developer. When the source of the change request is the client, manage effectively. If the source of the change request is you – perhaps you noticed an error or oversight – simply communicate this as quickly as you can while it is still possible to implement. If the necessary corrections are delayed due to a stuffy change control process, once again, efficiency has lost out due to formality.
Really, adaptability is the name of the game. Your functional requirements documentation process should adapt well to the working styles of the people on your team. When the focus stays on the function of the requirements documentation rather than the formality, the documentation will be effective and well-received.
To learn more about Tia Peterson’s experience with technical writing, business analysis and requirements elicitation and documentation, please visit her LinkedIn page here: [http://www.linkedin.com/in/tiadpeterson]http://www.linkedin.com/in/tiadpeterson