How to Write a Good Functional Specification

How to Write a Good Functional Specification

Functional specifications are an essential step in building quality software that you’ll want to support over the long term. They define the requirements to be implemented in the software. A good specification needs to carefully describe how the software will look and behave in all situations. Here’s some battle-tested advice for writing functional specifications that will work beautifully.

Make it a collaborative contract

In a software production organization, the functional specifications play the role of a written contract between the key stakeholders that collaborate in the making of the software. Here’s a list of what goes into making good specifications:

  • Product managers should ensure that all requirements are captured and all business rules are accurate.
  • Designers should define the user interface and interactions.
  • QA should be able to find enough information in the document to reflect the changes in tests.
  • Developers should find sufficient explanation to help them define technical specifications or directly code the corresponding features.
  • Technical writers should find answers to help them write meaningful user manuals and technical documentation.
  • Support teams should have a reference for qualifying customer reports as defects or normal behavior.

The specifications should be the trusted source for all teams to find answers about what the software is supposed to do.

Make it a living document

A specification is a living document that gets updated over the whole software lifecycle. While it can and should usually be started ahead of development, abandoning it along the way would be an unrecoverable mistake. But why would a lengthy text document be of any use when you have working software and good tests? Well, if you’re doing throwaway software such as a proof of concept, don’t spend too much time on your specification. But if you’re going to have several generations of developers writing and maintaining code for thousands of customers over many years, you’ll need a safety net when things go wrong. And your specification, if well written and up to date, will be that low-tech thing that you’ll be happy to have there to save the day.

What format to use?

Many popular specification formats exist. For example, user stories (“As XXX I can do YYY so that YYY”) work well for low-touch developments and agile practices. And use cases (“Step 1, then step 2…”) are very efficient for aligning with user expectations.

But which one is the best? There’s no silver bullet, and the general advice is to pick the one that matches the best with your organization and development practices. The truth is that everybody ends up with their own format.

At eXo, we have experimented with different things over the years and have converged to a preferred format that we find quite comfortable to work with.

Each specification is written on a wiki page, starting with:

  • a table that defines key information for the specification, such as title, description, name of the spec leader, target version, links to other resources, etc.; and
  • a rationale paragraph that briefly describes why this feature is needed—because you always Start with Why, right?

eXo wiki for Functional specifications

The main body of the specification is a screen-by-screen set of visual designs accompanied by a rules tables for describing interactions and the business rules that apply to them.
The rules tables contain an ID, a description, and optionally a priority and/or a target version.

Functional specifications document using Wiki

As you can see, it’s nothing fancy, but it works well for us.

Using a wiki makes the specifications easy to reach for all participants, because it has a built-in full text search, and we can organize the pages in a flexible hierarchy and link specifications together. And, of course, we can edit collaboratively on wikis.

Using a screen-by-screen approach, we include many visuals in the specification. Hence, understanding the big picture of a feature only takes a quick glance. When you want to dig into it, you can refer to the table of rules below the image.

Writing a good specification

Now that you’ve chosen a specification format, what do you actually put in the specification? What do you describe? What level of requirements is optimum? Here are a few suggestions for writing GOOD specifications that developers, testers, and business stakeholders will thank you for 😉

1: Include the designs, not wireframes

Start specifications by including low-fidelity wireframes or paper sketches. They will help you gather your ideas and provide excellent support for incepting an idea with a team. But as the design process starts, designers should produce high-fidelity visuals that developers will use to check their UI code. These designs should not just have “lorem ipsum” but actual text and labels, and you should pay attention to all details. In particular, the state of the application captured in the design should be realistic. Include alternative states in dedicated rules if needed. Also, don’t forget to include responsive alternatives if you’re working on a mobile web app. Everything should be consistent with the rules of the specification, but also with the behavior of the other existing features. Keep updating your specification with latest designs to make sure it reflects all decisions.

2: Write concisely

Specification text can easily become boring to read. So make it less painful by writing only what’s necessary. All your words should be there for a reason. You’re not writing a novel, so try to use short, straightforward sentences with simple, expressive verbs.

Also, name things consistently along the specification. For example, don’t call that button the “Validation button” somewhere and then the “OK button” elsewhere. A bit of styling can help with that. I use a script font to refer to names or labels, and use “quoted italic” for messages I want to be implemented verbatim.

3: Add examples

Sometimes expressing a rule with words leads to an awkward sentence, even after the third rewrite. When this happens, it’s a signal that you should add a concrete example to clarify your confusing words.
Use realistic data in your examples. And if you can, try to make your examples consistent and based on the same data along the specification. Thus, testers and developers will be able to easily turn your examples into datasets and test cases.

4: Skip low-level interactions

There’s a common belief that a specification should be exhaustive. Well, pretty much like software without bugs is utopia, there will never be a 100% complete specification. Just admit it and avoid falling into the trap of over-specifying upfront. It’s okay to skip some low-level interaction details when you know designers and developers will work to make it look and feel smooth.

Also, many details such as validation messages, animations, and some reusable UI component behaviors are actually already captured in the frameworks your developers are using. Detailing these low-level interactions would add redundant noise. Instead, your specification should leverage a companion UI/UX Guidelines document with components and patterns that you can tap into and expand over time.

5: Iterate and call for feedback

Even if everything is clear in your mind, you will rarely write a good specification in one go. Once you’ve reached a point where you think you’ve written down all your ideas, pause and show it to other participants (your peers, developers, testers, managers, etc.). Call for feedback, and come back to it the next day. This feedback loop, along with decantation time for your brain, will almost always make you change your mind about a few things. Or it will let you find out that you forgot things. Repeat this a few times before you submit your specification to other participants for validation.

At eXo, the product managers, quality and development engineers must all agree on an informal “go” on any specification before we consider it validated and start serious implementation work. Even after being validated, a specification continues to change, because while implementing the features, developers and testers will pinpoint a multitude of special cases or functional inconsistencies that you were absolutely certain you got right!

Writing specifications requires a strange mix of rigor, creativity, and humility, but it’s a very rewarding exercise that is easy to approach, provided you put enough passion!
No matter how you choose to do it, keep in mind that the best specifications are those that ease the software production process.

At eXo, all of our product specifications are publicly available, and we’d be pleased to hear your feedback on them.

Related Posts

Patrice Lamarque

I am the product officer at eXo. I oversee product management and product marketing. My teams design, create and promote the features of and improvements to eXo Platform. As a former enterprise software developer turned product manager, I have a passion for how IT can improve people’s lives. In this blog, I write about some of my personal interests, such as productivity, alternative forms of management and corporate organisations, collaboration, open-source and emerging technologies..


Speak your mind

Your email address will not be published.

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">