What Actually Goes in a Functional Specification?

There’s a lot of information on the Interweb about how to write a functional specification (FS for short, aka software requirements specification, system specification, product specification.

What I have struggled to find, though, is a good, detailed description of what should actually go in an FS and, in particular, to what level of detail. When asked this question, most BAs answer, “it depends”. Whilst this is true, I think we can improve on it by drawing some clear boundaries around how much detail is allowed, and how much is too much.

Therefore, I present a specification for a functional specification. This my own view and by no means an industry standard, but it works for me. :)

Who's allowed in the Functional Specification?
What Document are We Talking About?

Let’s be clear. I’m not talking here about a high-level business requirements document or a wish-list of stakeholder needs that may or may not be achievable, and which might even conflict with one another. The document I’m talking about here is the result of the synthesis of those needs into a coherent view of what the system will actually be.

This is the document that you:

  • Give to the developers so they know what to build
  • Give to the testers so they know what tests to run
  • Give to the stakeholders (and get them to approve) so they know what they are getting

Now before you start getting all agile on me…no, I’m not advocating a “throw it over the wall” approach to delivery, and I’ll talk later about the various forms that an FS can take. I just want to be sure we are all talking about the same thing.

Oh, and whilst we’re at it, let’s not call it a document. It might not be a single monolithic text-and-diagrams epic. So let’s just call it a thing, or even better, let’s go plural: things.  :)

I’m also primarily talking about the specification for a system that is to be built. Such a specification is not generally appropriate for a system that is to be bought off the shelf.

A Simple Definition of a Functional Specification

OK, now we have the preamble out of the way, here’s my simple definition of a functional specification:

A Functional Specification of a (computer) system describes the externally-visible behaviour of that system.

That definition might sound a little too simple to be true. Surely there’s more to a system than just what the users see. You’re right, there is. And once I elaborate on my definitions of system and externally-visible behaviour (specifically, I don’t mean just use cases), hopefully you will agree with me that the definition is both complete and precise.

What is a System?

I like to think of a (computer) system as a black box. The black box has two interesting features:

  1. Interfaces, through which external entities can interact with the system via a series of inputs and outputs. There are two types of external entities – humans and other systems (also collectively referred to as actors of the system), and we need to worry about them both.
  2. State, which changes as a result of interactions with the actors. Think of this as the system’s memory, in which it remembers (or stores) data - usually implemented as a database.

This simple definition applies to pretty much any system you can think of. All systems have interfaces – without any interfaces, a system is just a rather uninteresting black box! Most systems have (human) user interfaces, but I’ve also worked on plenty of data processing systems with no UIs – they just take data from one system, process it, and pass it on to another system. Some systems do not have any system interfaces, but in these days of end-to-end integration, most systems do. Some very simple systems do not have any state, although most interesting systems do (any system that manages data has state).

One of the most important things to get clear for a system under design is where the system boundary lies, and you can do that easily by identifying its interfaces with the outside world.

Here’s a simple diagram of a system (called eShop), showing its interfaces and the actors that use those interfaces. I call this a context diagram.

An example context diagram

An example context diagram

 Two Key Elements – Functions and Data

Armed with my definition of a system, I can now say that there are two key elements to a functional specification:

  1. Functions – a description of the interactions between the system and its (human and system) actors
  2. Data – a description of the state of the system

Once you have described all the functions and all the data (to the right level of detail), you are done – simple as that!

Describing Functions

The functions of a system are the interactions that can occur between the system and its actors (through the interfaces). An interaction is a sequence of actor inputs (e.g. a user clicking a mouse button) and system outputs (e.g. displaying some data on the user’s screen). Typically the actor is trying to achieve some objective (log in, search for data, update data, perform a calculation etc.).

I like to use use cases as the main anchor for describing a system’s functions. They are, to my mind, the perfect format for describing interactions between an actor and the system. Laura Brandenberg has a similar love affair with use cases. I’m not going to explain use cases in full (you can click here to read what a use case is), but just in case you’re new to this game, a use case looks something like this:

Use Case 1: User Logs On

Main Flow

  1. User launches the application
  2. System prompts user for log-on details (user name and password)
  3. User enters log-on details and submits them
  4. System requests user’s log-on details from the external single-sign on directory
  5. System validates that user’s entered log-on details match those from the directory
  6. System displays the main menu

Alternative Flow 4a: Incorrect log-on details

  1. System tells user their log-on has failed
  2. Return to Main Flow step 2

Alternative Flow 4b: User account locked

  1. System tells user their account is locked and they should call the helpline
  2. Return to Main Flow step 2

I’ve omitted some of the key parts of my use case for brevity (e.g. pre- and post-conditions), but you should be able to see that it describes the sequence of inputs (by the user) and outputs (by the system) for a given function. For more info on use cases, read Writing Effective Use Cases by Alistair Cockburn.

Note that the example use case shows interactions both with a human user and also an external system (the single-sign on directory). In order for your use cases to be complete, you need to cover all the interactions through all the interfaces, whether they be human user interfaces or system interfaces, in particular including any “back-end” systems.

It’s also important to understand that use cases do not give a fully-detailed description of the system’s functions. Rather, they are the anchor for the functions, around which the other details can be added. Adriana Beal has some additional comments on this topic in this article.

Functions – How Much Detail is Allowed?

OK, we’ve done the easy part – most people agree that use cases rock, and all I’ve been doing so far is setting the scene. The tricky part is deciding how much detail to include either within the use cases or alongside them.

Here’s my simple answer:

  1. You are allowed to include full detail of any externally-visible behaviour of the system (including behaviour through system interfaces).
  2. You are not allowed to include any details on the internal workings of the system.

For example, you are absolutely allowed to include:

  • User interface details, right down to the very last pixel and colour shade
  • Size and allowable contents of data input fields
  • Whether a specific input control is implemented as radio buttons or a drop-down menu
  • Exact text of error messages
  • Complex business rules and algorithms
  • Supported web browsers, client operating systems, screen sizes

Some people will argue that some of the above examples are aspects of the design, and have no place in a requirements specification. There’s a long debate on this topic in my previous article, Requirements Versus Design: It’s All Design. But whatever terminology we use, my experience is that business stakeholders, developers and testers care about these details, and thus they have every right to be included.

In particular, the UX design might be put in a separate document, maybe even produced by a separate person (a UX designer), but in my world-view, it is still part of the externally-visible behaviour and thus part of this “thing” or “things” that I am calling a Functional Specification.

Here are some more things you are allowed to include:

  • Exact format of a system log
  • Physical format of a system interface

These are slightly more controversial because they are of little interest to our primary business stakeholders, and certainly have a “technical” aspect to them. Nevertheless, they are externally-visible behaviours of the system and are of interest to other stakeholders – a sys admin, or the developers of an external system.

Also allowed are the externally-visible qualities of the system, such as:

  • Performance (system response times)
  • Volumetrics (number of concurrent users) – current and future
  • Concurrency characteristics
  • Security characteristics (notoriously difficult to specify effectively)

Such qualities are commonly referred to as non-functional requirements – a term which I really dislike because they are so obviously not non-functional. But the term is pretty-much ubiquitous, so I guess we’re stuck with it. :)

Describing Data

First of all, let’s resolve a contradiction. I’ve said that the FS should describe the externally-visible behaviour of the system. But the system’s state isn’t externally visible (unless you go poking around in the database), so why include it? The answer is that the system’s state has an important effect on its functions. A function which updates the system’s state has a delayed effect in that it affects any other function which outputs the same data. Functions and data are intertwined and you can’t really describe one without the other.

The usual way to describe system data is in terms of (logical) data entities. An entity is a “thing” of interest (a customer, an address, an order, a product). Entities have attributes (a customer has a first name, a last name, a date of birth etc.). Entities also have relationships with one another (a customer has one or more delivery addresses; a customer has zero or more orders; an order consists of one or more products).

Data – How Much Detail is Allowed?

Here’s what detail I consider to be allowable for data:

  • Entity name (so that it can be unambiguously referred to)
  • Entity description (explaining what the entity actually is – not always obvious)
  • Attributes:
    • Name
    • Description (again, not always obvious)
    • Type and allowable values, such as:
      • String, max 50 characters
      • Integer from 0 to 60,000 or blank
      • One of Male, Female or  Not Specified
  • Relationships with other entities:
    • Meaning of relationship (e.g. home address, delivery address)
    • Multiplicity (one-to-one, one-to-many, zero-or-one-to-one etc.)

Note that the above are logical, rather than physical, definitions. For example, a logical type of “Male, Female or Not Specified” might be implemented as a NUMBER where 1=Male, 2=Female, 0=Not Specified, or it might be implemented as a nullable VARCHAR where “M”=Male, “F”=Female and NULL=Not Specified

Not allowed:

  • Physical database definitions (table names, column names, column types)
  • “Entities” that are actually database tables implementing many-to-many relationships

OK, So How Much Detail Do I Actually Include?

So far, I have stated the level of detail that, in my view, is allowed in an FS. The obvious next question is whether you actually need to write down all that detail. And here’s where we get back to the original answer – “it depends”.

It depends on a variery of factors, such as:

  • How much your business stakeholders care about the details
  • How much detail your developers want you to give (or alternatively how much you trust the developers to do something sensible in the absence of detail!)
  • How much detail your testers want you to give
  • Whether you are specifying a new system or enhancements to an existing system – an existing system has existing patterns which can be assumed to apply to enhancements, such as look & feel, data validation rules and so on
  • How much you rely on non-written communication

My own experience is that every organisation is different, and for each new assignment I need to find the appropriate level of detail that needs to be written down. Here’s what happens when I get it wrong:

  • I give too little detail and the developers makes a “wrong” assumption
  • I give too much detail and I spend more time than necessary writing it all down
  • I give too little detail and the testers keep coming back for more detail
  • I give too much detail and the developers and testers work exactly to spec instead of challenging its deficiencies

However much detail I decide to include in, or omit from, my written specification, I am always clear where the boundary of my accountability lies – I am accountable for all externally-visible behaviour of the system – so if I choose to leave some detail out, I accept that I am giving the developers some free reign, but that it’s my problem if the stakeholder doesn’t like it!

And What Format Do I Write It Down In?

So far I have talked about a thing called a Functional Specification, and you might have assumed that I am thinking of a single, “traditonal” text-and-diagrams document (such as might be authored in Microsoft Word). But of course there are many alternatives, especially when you start looking at agile approaches. Here are a few options:

  • A formal requirements management tool, such as Rational Rose
  • Use cases in a spreadsheet combined with an HTML prototype (see my previous article, An Agile Functional Specification)
  • Use cases, data and business rules in one document, UX design in a separate document (perhaps produced by a separate UX designer)
  • User stories and acceptance criteria scribbled on index cards (as per XP)
  • A graphical format using a drawing tool such as Microsoft Visio (something I am experimenting with at the moment)
Regardless of the format used, the same rules about type of content and level of detail still apply.

A Curveball or Two

So far I have said that a functional specification should only describe externally-visible behaviour. I have already made a minor exception to this rule by including the system state, which is kind of internal.

There are some other exceptions, and they apply in cases where it is important constrain the (internal/technical) design of the system. Here are a couple of common examples:

  • For a software product, defining the platform(s) on to which it must be possible to deploy the software (e.g. “compatible with Windows Vista and Windows 8 with 2GB of RAM”)
  • Extensibility requirements – how easy it must be to extend or alter the system. This is a whole topic in itself.

I try to treat these very much as exceptions to the rule and only include them where they are absolutely necessary.

In Summary

To summarise then:

  • If a system is a black box with (human and system) actors interacting with it through interfaces, then…
  • A functional specification describes the externally-visible behaviour of the system
  • There are two key elements – functions and data
  • Functions are commonly anchored around use cases
  • The theoretical scope includes all externally-visible behaviour, right down to the last pixel…
  • But as to how much detail you actually include…it depends…
  • And you are still accountable for all the details that you omit
This entry was posted in Articles on by .

About Tony Heap

Tony Heap is a freelance Business Analyst Designer based in the UK. Having worked on a variety of projects both large and small, he feels like he has a few experiences to share. He is particularly interested in agile approaches and how they apply to business analysis.

34 thoughts on “What Actually Goes in a Functional Specification?

  1. Thrigun

    Hi Tony,

    My name is Thrigun, from Bangalore, India.

    Am working as business analyst in health care domain.
    I liked this blog written by you because even i have experienced similar thing when it comes to writing functional spec; the format, use cases, data fields, wireframe design etc. This is a great infor you provided as its from your experience. I have written functinal spec with most of the details you have mentioned.

    I liked the way you have defined a functional specification, its main elements- function and data and one use case believe me i have written same way i mean the format you have mentioned its the same i used to write and i learnt this from my experience in my previous organization.

    Thanks very much for sharing your experience.

    Thrigun

  2. Pingback: What Actually Goes in a Functional Specification?

  3. Alexandra Cordes

    Great post.

    I like how you have broken down the functional specification into two key elements: functions and data. You have explained very nicely that even though data (state) is not really a externally visible feature there is an important relationship between the functions and state due to the fact that functions alter the state of a system. This explains with greater clarity the importance of data requirements.

    I also like that you mentioned when it is appropriate to deliver an FRS, i.e., when a system is being actually built as opposed to being purchased off the shelf.

    Interesting statement about those non-functional requirements being a misnomer. I will have to think about that one. Food for thought which might start a new debate! :)

  4. Pingback: Functional Requirements | Project Wolverine

  5. Anzelika

    Hello, Tony,

    Great article! Agree with your view absolutely.

    When describing data, I add a couple of more things:
    1. Whether an attribute is mandatory or not (for input/output)
    2. If it should contain unique value
    3. Default value, if needed

    1. Tony Heap Post author

      Glad you liked it Anzelika! Good call on the extra things to mention for data – I usually include these things under the heading “type/allowable values”, for example:
      - Integer from 1 to 100 or unspecified (for an optional attribute)
      - Positive integer, must be unique
      I don’t normally mention default values. I prefer to specify the values to give each attribute of a newly-created entity explicitly as part of the appropriate use case(s).

  6. Laura Brandenburg

    Tony,
    What an amazing article. I really like how you’ve broken down why you include specific details and how you’ve found things to work well for you in the past. I bet this one proves to be a standard-bearer. Nice work!
    Laura

  7. kai

    Love this post Tony! I was not clear..were you saying the data, and UI should be in the form of a Usecase??

    Also i just finished a project on a new “Employee BOnus program” currently done by hand by the HR team. So I did do a Highlevel “AS-IS” and “To-Be” diagram in visio.

    Then in the detailed requirement-I did the requirement for each screen and calculations. Plus it had a dictionary with the bonus computations.

    Question-I had no usecases because I was thinking the MEAT of the project was on the new program to process bonuses not the roles of the actors because their roles were the same as before. So based on your article should i have done “system” usecases showing the sequence of how the data went from the Payroll system, HR system to the Bonus system to the check printer???? If so would I not just do a process flow diagram vs a usecase in this type of project?

    1. Tony Heap Post author

      Hi Kai,

      I’m not going to attempt to give a full description of use cases and when & how to use them (for that you need to read Writing Effective Use Cases by Alistair Cockburn). The main thing I want to clarify, though, is that when I say a “use case”, I do *not* mean a use case *diagram* – I mean use cases in their written form, describing system functionality in detail. I don’t generally draw use case *diagrams* – I find they don’t usually add much value.

      A process flow diagram (or flowchart) is a good alternative to a (written) use case, and I have had some recent success myself using flowcharts to describe system functionality (there’s an article on its way!) Each box in the flow chart is the same as a single step in a use case flow. The main thing is to make sure you get the right level of detail either in, or with, your diagram.

      1. kai

        Thanks Tony. I will get the usecase book. Do you have a book you can recommend to strengthen my visual modeling skills and knowing which model is best to use when?

      2. Tom Miller

        I am not sure if I can make a distinction about “which model” to use but I will note that there is a BPMN which in turn feeds into Business Process Modeling systems (BPMS). This is all visual and modeling and there is at least one free editor/process modeler out there as well as a free BPMN addon for Visio.

        Tom

  8. Pingback: To spec or not to spec, that is the question… » pseudoplace.com

  9. hannah smith

    Hey Tony,
    Loved the article and really interested to read your article on Process maps and how they can describe system functionality. I’m about to embark on a new project at work (Minsterlaw.co.uk) which will initially involve me mapping out the ‘to be’ process. I’m going to start with chunky milestones which I’ll then aim to breakdown into more detailed steps and activities. What I think will become apparent though is that the process isn’t going to follow a typically logical path, I have a haunch that any part of the process could be triggered at any time, largely because it involves interactions with clients as well as a number of other suppliers (third party insurers, the MOJ). I think there will be some business rules that the system must look to support and so my questions is – how would you advise me to capture the Rules? Should I make reference them to them on my process map via a notation and then capture the detail of the rule in Rules catalogue? Amy advice would be much appreciated

  10. Tony Heap Post author

    If there’s one thing I don’t like it’s a business rules catalogue! Whenever I have seen one of these it’s always been an unstructured pick-list of some subset of the requirements that occurred to the author or stakeholder at the time.

    I much prefer to describe the system behaviour as sequential steps (either verbally as use cases or graphically as process diagrams) and include the relevant aspects of the system behaviour along the way. Importantly, I make sure that the “rules” are associated with the relevant step, not just written down as an unstructured/unordered list list.

    With written use cases you can include the detail within the use case text (perhaps indented to separate the detail from the main purpose of each use case step), or as footnotes (although this can get messy if there are too many).

    With process diagrams, I include the details in call-outs attached to the relevant process steps. The key trick here is to get the look & feel of the digram right – the notes need to me small & discrete so as not to detract from the main process flow. I tent to use a smaller font and a mid grey colour, so that the notes fade into the background unless you actually focus your attention on them. One of these days I will finish that article!

  11. hannah smith

    Thanks for this Tony, I really appreciate your advice. You’ve given me some useful info here. I quite agree with your view on rules catalogue and I’m not sure the developers I’ll be working with would appreciate a ‘catalogue’ either. I’ll definitely look to start annotating the process with call outs, think that’s a great tip and one that will no doubt help maintain the overall picture of what we are trying to achieve. Thanks again Tony.

  12. Tracey

    Hi All
    Great Read Tony – many thanks.
    I read this with interest because I wanted to find out what is in an FS, thinking this is the type of document I need for my project. But it turns out, maybe not. We’re implementing a COTS system but it requires a degree of integration with legacy IS Systems – such as LDAP or Active Directory and I thought the FS was a way to describe the why the business want to use this technology and what the end result would be. Is this still called an FS?

    I also agree with your business rules method. I also use Viso a lot to draw the use case, or flow and number the boxes, I then have a narration document to go with the numbering which gives me enough room to explain in more detail behind the box, including any rules. I find this way easier than putting them on the flow it self. It also gives people the option of those who perfer text over diagrams and visa versa.

    Use cases themselves with Actors and boundories and things have completely confounded me and I can’t use them at all!! I have tried many many times.
    Rgds
    Tracey

  13. Tony Heap Post author

    Hi Tracey,

    I’m working on a COTS implementation for a large retailer at the moment, including a whole bunch of legacy integration.

    With it being a large project, there is a lot of documentation, but there are three doc types that together describe the functional design of the solution:

    1) A “solution overview” doc – this identifies the various applications (COTS and legacy) and shows how they interact in general terms. It also lists the business processes that are impacted by the new solution and summarises how they are changing.

    2) The business process models. These are swimlaned flowcharts showing how each business process is executed, by whom and using which systems. It also shows the automated steps (including where data is transferred between new COTS and legacy). These models go down to what we call “level 4″ detail – one level above full detail – the full detail isn’t needed because it’s in the COTS user guides. The models also call out which process steps are changing and which remain as-is.

    3) Functional specs for any system integrations or COTS modifications – i.e. anything that has to be built from scratch.

    1. D.

      Curious to know where you would include the details of how a COTS system is configured to meet business needs?

  14. Jacqui

    Hi Tony,
    When I read your article a few months ago, I felt as if you were describing my woes. I used to produce wonderful, detailed specifications, that no-one read. It was just too much to wade through the document.
    I followed your advice and have just used the template to spec a new system. It is much easier for me (it helps me stay logical), and much easier for the developer to follow.
    I don’t believe in blindly following rules, and always adapt to the current needs. Thanks for providing a basis to work on.
    Jacqui

  15. Jacqui

    Click the link within this article to *A Graphical Functional Specification – Part 2*, and then click the link in the paragraph *You can download an example graphical functional specification in both PDF format and (zipped) Visio format*. I suppose that I should have added the comment there. :)

  16. D.

    I totally agree with you on where to draw the line….I have described it up until now as those things that directly impact the user’s experience. Your article gave me another way of articulating it. Thanks for your insight!

    1. Tony Heap

      COTS is different – in this case you often see a config spec rather than a functional spec. The config spec would be agreed with the customer, since the configurations typically affect the user-visible functionality.

  17. Tejo

    Thanks for this great story. I think you can put it even simpler: A FS should contain all information that a developer or team of developers need to develop a product that meets the customers expectations, without having to go back to the customer later for more details.

    Every little detail the customer cares about, how stupid it may be, should be in there, for the developer to make a product the customer likes. The other way around, if the customer doesnt care, and the developer doesnt need it, or can decide for himself, it should not be there.

    This is of course not 100% realistic, but it should be the target, imho. This definition includes your division into interfaces and state, without describing these it is impossible for a developer to develop the application.

  18. Jacqui

    Hi Tejo,
    You wrote “A FS should contain all information that a developer or team of developers need to develop a product that meets the customers expectations, without having to go back to the customer later for more details. Every little detail the customer cares about, how stupid it may be, should be in there, for the developer to make a product the customer likes. ”

    Developers are not usually great readers. Put in whatever they need to get the job done correctly and make sure that you are available to provide all the other input to help them. They are not business oriented, you are.

    Jacqui

  19. Philip De Wet

    Hi Tony

    Amazing article. I would like to know what would your answer be if you have a COTS solution like SharePoint that would require configuration how would your definition of the FS differ if any. I mean Microsoft would have all the relevant documentation of SP so would the FS only contain the specific configuration components?

    Regards

    1. Tony Heap

      Hi Philip,

      Typically I produce a separate Configuration Specification to describe how a specific instance/deployment of an application is configured. For example, I once designed an app which was deployed as three separate instances, each with a different configuration. I produced one FS and three Config Specs (one for each instance). If you have *bought* a COTS product then in theory it comes with an FS and you only need to produce the Config Spec.

      SharePoint is an interesting one though, because it a very general purpose application that is so highly configurable that you can almost create new functions just by configuring it. In which case you might want to produce an FS after all. However, there is little point in re-describing all of the out-of-the-box features (unless your business users really wanted you to for their understanding). Rather, you would only describe the “interesting” bits – the bits that need configuring/building.

  20. Charmaine

    For once I feel like I actually understand what goes into a functional spec. Thank you for a well-written article. I look forward to reading more of your articles. Keep up the good work.

    I didn’t quite understand your comment about non-functional requirements, you say they are “obviously not non-functional”. Does this mean that they are “obviously functional”?

  21. Tony Heap

    I suppose it’s a language/terminology thing. The term “non-functional” implies that NFRs are nothing to do with functionality. But actually they describe some aspect of the system’s functions (e.g. how long it will take to execute a given function, or what accessibility standards the UI will confirm to, or which functions a given user is authorised to use).

    Hope that helps.

  22. Irina

    Thanks Tony. Very very helpful article.
    Do you ever create the prototypes yourself as well? if so, how are you keeping track of the screens and how are you referring them in a Functional Specs document?

    best wishes

    1. Tony Heap

      Irana,

      There are various ways to cross-refer between the FS and the prototype, and it really depends on the format of your FS. If you are using written use cases, then mention the screen names within your use cases, for example:

      1) User enters a search request
      2) System displays matching products (Search Results screen)
      3) User selects to view a specific product from the matching products
      4) System displays details of the matching product (Product Details screen)

      Alternatively, you can include the prototype and the FS within a single, graphical document

Comments are closed.