Be smart about documentation to get the best from your software developers
When you’re looking for a software development partner, you are bringing in expertise that’s needed to achieve your vision for your products and/or services. You need to give your development partners a brief so they can deliver what you’re looking for. Yet you also want to leave enough room to benefit from their technical skill to realise the fullest potential of your vision.
The documentation you prepare will provide the steer for your project, so how do you gauge the level of detail needed to get your project onto the right track?
Requirements or Specifications?
In project management, product development and software development it is useful to distinguish between requirements and specification documents. Based on our 25+ years of experience in software development, we operate with both Functional Requirement and Specification documents. Here is our definition of each and when they should be used.
Functional Requirements
A functional requirement is a statement of what a software system or component of a software system must offer its user(s). You want to have a list of functional requirements for a software development project, which together will outline what you need the software to do. This is a high-level document created at the very earliest stages of the project, though it may be amended or added to later.
Specification
A specification is a detailed, usually technical, description of how the needs (or functional requirements) of your software will be met. Specification documents are generally much longer than functional requirements documents and you may have a series of specifications each dealing with different elements of the project. They are written after the functional requirements are signed off and take shape as the project is scoped.
Clearly, you don’t want to expend a lot of people hours on writing a full specification if this isn’t needed before you engage your developers. In fact, it may even be a hindrance.
Whether you provide only the functional requirements or these plus a full specification to your developers depends on the level of control you want over how your software is built and how much of your software partner’s valuable expertise you want to make use of.
You may need a full specification if
- specific constraints or compliance requirements exist
- work has already started on development
- you have a very specific idea how your software should be built
- your outsourcing team don’t have experience with similar projects
Specific integration or compliance requirements
If your company operates in a space with stringent compliance requirements (for example in the medical or finance sectors) you will probably have a number of specific technical, security or other requirements that must be met by your software.
Similarly, the more specialised the systems and programmes your new software must integrate with, the more important it is to document all these needs. Sometimes the best way to do this is by creating a detailed specification.
Depending on your developers, the specification may not need to cover the whole project and could concentrate only on the compliance and/or integration requirements.
Development work has already started
Another situation where a technical specification is useful is where development work has already started and you are handing over to a new team. To avoid unnecessary duplication the new team will need to know exactly what’s already been built, why it was built that way and what the specification is for the rest of the project.
Your new team may want to take a very different approach and, as you’re investing in their expertise, it’s probably a good idea to hear them out. If, for example, you weren’t completely happy with the output from your previous team you should consider giving your new team freedom to redesign the specification.
Outsourcing team aren’t experienced with similar projects
One reason to write a full specification before starting work with your developers is when you know they don’t have much experience with projects like yours. For example, they haven’t worked in your industry before, don’t have experience with your systems and hardware or of working within your compliance requirements.
It may also be worth considering if you’re working with the right partner. With a group who have worked on similar projects you’re likely to see quicker progress and fewer unexpected set-backs. This means you get a better product, faster. You can write a specification to plug the experience gap, but is that the best use of your in-house resource and what does that mean for the quality of the output?
You have a specific idea for how to build the software
If you’ve already decided how the software should be built and invested time and effort on a technical document then it makes sense to share this specification with your software developers.
A word of warning, however, that if you’ve chosen your developers well they might have other ideas. If you’re bringing in developers who are highly experienced and adept at problem solving, they can almost certainly add a lot of value to creating the specification. At BioMedical, for example, we partner with our clients to first understand what you really want to achieve and work together to design the most effective way to get there.
Focus on the functional requirements when
- there’s not yet enough internal alignment on the purpose and objectives of the software project
- you don’t have time and/or expertise to write a full specification
- you trust your software developers to create a better technical solution than you can
- you want cutting edge expertise to help find the best way of achieving your aims
Don’t yet have full internal alignment
You need agreement on the functional requirements before the specification is written or you risk wasting time re-drafting it. Or worse, you could waste time and budget on recoding parts of the software when requirements from stakeholders or different business areas become apparent much later in the project.
Listing and internally reviewing the functional requirements is a valuable process because it smoothes the path of development and testing later. If you’ve chosen the right software development partner, they will start with a robust understanding of your objectives and then support you with the specification that will meet them.
Not enough time/expertise to write specification
If you’re looking for an external partner because your team do not have the time needed to develop your software, they almost certainly don’t have the time to develop the specification. The same applies for expertise. Rather than spend a lot of time and effort on a specification that isn’t complete or isn’t as ambitious as it could be, you can look to your development team for help.
If they aren’t able to support you with developing the specification, we’d suggest you look more carefully into whether or not they have the expertise to deliver the software.
You trust your developers to create the best technical solution
If you’re bringing in a development team because you know they will create a better technical solution than your in-house team, why wouldn’t you want their help in developing the specification?
You may be concerned that this will add to project costs. However, your partners will be building the software and you’ll probably find they’ll contribute better technical ideas, be more up to speed on the project and be more personally invested if they’ve been involved in the specification. This usually means the entire project will be more tightly run and therefore more efficient.
Cutting edge expertise is needed to achieve your aims
Similar to the above point, if you want cutting edge expertise from your development partner then you’ll want to let them contribute to the specification.
By handing over a specification document, you’ve potentially wasted time developing something that needs to change to accommodate the technical knowledge you’re buying in.
You also run the risk of your developers ‘working-to-rule’: following your specification even when it’s flawed and it may not actually deliver on your requirements.
Maximising the potential for your products and services
At the end of the day, you’re not investing in a bespoke software project in order get something only just good enough (or worse, not even good enough). You are bringing in an external partner because you want to realise your vision for your products and services.
(If you’re not sure how to choose a suitable software partner, our article ‘12 questions to ask potential software development partners’ might also be useful.)
It may make sense to present a detailed specification to your software partner, especially for any of the reasons listed in the first part above. However, we’d still encourage you to stay flexible and open to their suggestions.
In our experience, the most successful software projects are started with a balance of being specific enough about your goals and objectives to give a good steer, while being flexible enough to make the most of your development team’s expertise. If you hire the right partner they will ask questions, bring a problem solving mindset and be ready to challenge you in order to achieve the best for your project.
Want to realise the full potential of your project? Contact BioMedical to discuss it with us.