How to Build a Software Specification Document

We’re entering a time when most professional’s day-to-day work touches some aspect of code. At Mayven we are seeing more and more teams turn to software development to solve problems and be more productive – from integrating Salesforce APIs to creating products and applications to interact and better serve their customers.

What this also means is there are a lot of people building software without a lot of software development experience, and a lot of times their projects go really poorly. Not to worry! At Mayven we help to walk you through the process of what it takes to do great software development and get you ready for a successful project.

A big reason these projects don’t go well is people start projects under prepared and they don’t even know it, because they haven’t seen a *great* software specification document. So, that’s what we’ll talk about today.

So, What is a Spec?

First, a few caveats about what we are discussing:

• We are talking about software applications, which we are including as web, mobile and desktop (macOS, .exe) software development
• Simple Marketing sites, WordPress Sites, Landing Pages, Email Templates, etc are excluded
• Different types of projects have different requirements for a great specifications document, which we won’t cover here, e.g. iOS vs web app
• This applies to *any* programming language and framework

Okay! So now that we have that out of the way, let’s think about software development like a custom built house. In most cases, you, the person needing to build the application, is like a developer (or if you prefer in this scenario you prefer to be some rich land baron building custom homes, that’s cool too):

1. You hire an architect and a land survey, to document what you have and what you are looking to build
2. The output of this is a detailed plan for what your construction team will build – the blueprint
3. Your construction team builds the house, layer by layer until a finished product is completed
4. Inspectors review the build and pass (or fail) when it is up to code
5. House goes up for sale

Now, we take those same steps and apply that to software development:

1. You create a plan that documents your current systems (if any) and what you are looking to code
2. The output of this is a detailed plan for what your development team will build – the spec document
3. Your dev team builds the application, module by module until it is ready for testing
4. QA & Testing team reviews the application and tests it to make sure it is to spec and pass (or fail)
5. Application goes into production

How to get a specification document DONE:

In the case of software development, most teams do not need to hire someone to build their specification document because they have that expertise in house and can prepare a really good spec. For teams that need extra help, most software development teams have services available to create software specs for a fee.

Not all projects are the same, and not all specifications are the same. However in all cases, the goal is clarity around features and setting expectations on what the final product will be. A great specification document is the how, what, and why of what you are looking to develop, in detail. It is important to be clear and document your spec in as much detail as possible. For larger applications these documents can be 100+ pages, so you can see how important it is to spend the time to go into that level of detail! Smaller applications require less documentation but the process is the same.

Here’s a list of boxes to check when you are creating a specification document that is ready for development:

• Write a summary of what the application should do
• Document all of the user personas in the application
• Document all of the process flows that a user would go through in the application
• Wireframe all of the views in the application that the user will see and include
• Design all of the views in the application and include
• Document all third-party integrations and APIs
• Create a functional specifications document that outlines all desired features
• Package all assets and files together

Some of these steps may require outside help – design and wireframe is a great example. And some projects may not require all of the steps, but the overarching goal is to get as much of the application documented and outlined before any code is written. This helps reduce rework, bugs, errors and issues. Back to our house example – changing the development spec midway through a project is like changing the layout of a house after the foundation is poured – you’ll be doing a lot more than ripping walls out.

Functional Specification Document Examples:

To get an idea of what I mean by great spec documents, here are some excerpts from spec documents we created that are pretty good. This is just a brief overview, but you should see the level of detail required. Most of these docments are many pages in length.

Table of Contents Example:

Here is an outline for a user persona:

For different parts of your application, documenting the process flow chart is important, which can be done in Visio by Microsoft, or any number of wire framing and documentation tools, like Balsamiq. Another good way to document feature requirements is listing them in excel as functional specifications.

If you still need help creating your specification document, come and see us at Mayven Studios. As part of the development process we can help you create great documents that you can take to any developer and have a great result. For more detailed specification examples, create an account on the site and send us a message! https://mayvenstudios.com/contact-us