How to write a software technical specifications document
A technical spec document is a must for any software development project
If you are building a house you make a plan before you start off. Software projects aren’t any different to this. All kinds of projects benefit from refined expectations and detailed requirements. Planning ahead helps you to avoid problems down the road.
Large companies put an overly strong emphasis on writing detailed specifications while smaller companies tend to dismiss their value. As is so often the case, the truth is somewhere in between. In the following you will learn what it takes to write a good technical specification.
What is a project technical specification?
The technical specification of a software project mainly describes the core idea and goals. It explains what business needs behind the idea will be addressed and how the end-user of the software will use the product. A great software specification will guide the reader along to understand the project, without having to investigate or ask numerous questions. Usually the purpose is to explain the need of the project to a potential software vendor.
Software can be tweaked easily. Do I really need to write specifications?
While it’s true that changes in software projects are easier to implement than with physical projects such as a house, it comes with downsides. It might delay your project and end up more costly. Development isn’t cheap. Writing a good specification document helps to ensure your project delivery goes as smoothly as possible.
What are the goals of a technical specification document?
A technical specification document, in the case of a software project also referred to as a “software design document”, is aimed to provide an entry point for externals. On a high level, its goal is to understand the goals of the software and guide a potential software vendor on how the project is expected to be managed for both the customer as well as the vendor. The technical spec should help with:
- Defining deliverables: What features are expected and in which way should they be delivered? The deliverables are split up into milestones, if the project is larger. These milestones usually contain an isolated aspect of the project and aim at being usable by themselves.
- Environment: How does the software operate in daily business? How does it fit into the existing IT infrastructure?
- Ways of communication: Who is managing this project on the customer end as well as on the end of the vendor? Key people such as project managers are usually set early on and stay on throughout the whole project.
- Clarify the details of collaboration: This includes expected project updates and meetings. This ensures both sides have a clear understanding of how the project should be executed. Generally, it is wise to review the software build regularly while it’s getting developed.
In the following we will go deeper into the topic by structuring these points more.
How to write a good project specification for your software project
A good software specification doesn’t just describe the features in detail, it guides the reader in learning about the core ideas in all major aspects.
As with many documents, you want to introduce the reader slowly to the story. The following two points will help your reader get started on the project:
Title page: Share the current working name of the project, if already defined. Don’t forget to include you as the author with contact details in case of questions. If you’ve got your project team already assembled, you should mention it as well. Often software engineers know each other from meetups or other social events. This can help to make the communication more smooth.
Brief Summary: Share the high-level purpose of the project/product you are planning to build. This shouldn’t be longer than 5 lines of text. Skip details about features and concentrate on the high-level picture here.
Feature overview and environment
Diving a bit deeper, the idea takes shape, the users and the environment get described further:
Core Features: What should the software “do”? Describe the functionality grouped into sets without going into the nitty gritty part yet. Share which business processes/functions should be managed/automated with the software. If your project is a website, include the expected hierarchy of pages. Table overview works well for any non-website project. Keep it brief at this point.
Users and roles: Who is using the software at the end and what are they trying to achieve? Describe the user groups with their background. The individual experience level of the users gives the software engineers insights too: A software for accountants requires a different level of detail in the user interface than a generic contact form on a website.
Environment: How should it be accessed? Is this a desktop software or a web application? What technology (e.g. operating system and browsers - including versions) should be supported? For web-applications and websites, information about the browsers are important. Version information such as “Firefox: current version minus two” are commonly understood. Project scope and costs depend on your required level of platform support. Keep it as low as possible, but as high as needed to make it work for your organisation.
Constraints: This is the moment to mention your corporate identity (CI), style guide, etc. You can append these documents in your emails or share links to relevant sources here.
This is the moment to dive deep into the features. Similar to the previous high-level features, write a section for each core functionality. Describe the expected workflow. Mention the information entered, load/saved and displayed.
Graphics, even freehand sketches, can help with understanding of the goals. A designer can help bring sketches of user interfaces into order.
User stories are a good way to clarify workflow with more details. These are theoretical scenarios describing how a feature would be used by one of the end users. Include all steps such as input, clicks and similar actions needed to complete the user journey. Describe the expected outcome as well.
Don’t forget to include information about the required permissions: Usually not all parts of a software product are accessible by every user. Make sure to reference the user group from the previous section here. Alternatively, a permission table can make sure nothing is forgotten.
Depending on the complexity of the feature, each of the sections should take up between a half page to two pages at maximum. If you exceed two pages you should consider splitting the feature further or reducing details and adding these to a general section.
Software doesn’t exist in a void anymore. Often software interacts with other software. This can be through interfaces (APIs) to services or external databases. Examples could be email services or services providing real-time data such as stock prices. Describe any systems which your project needs to integrate with. Share any details such as links to documentation.
What should I keep in mind when writing the specification document?
So far this all sounds straightforward. Yet writing a software design document comes with it’s own challenges. Most people won’t write it out off-hand. It makes sense to write a first draft quickly and add details as you go through iterations of reviews. After two to three rounds of reviews it makes sense to welcome additional feedback from other team members or project managers in your company. This way, you ensure you aren’t missing any important points.
Document collaboration tools such as Google Docs are a great way to share your draft with others. These online applications will make your work much easier by avoiding sending files around and incorporating updates from various ends.
Whether it’s your first software specification as a new project manager or you decided to outsource development for your passion project to a freelance software developer, it doesn’t matter: either way it makes sense to spend the required time to write it all down. This process forces you to become clear on the key questions of your project.
If you’ve got the chance to get feedback from a software engineer make sure to share it with him or her. Engineers have developed an eye for open questions over time.