1. Writing Functional Specifications
JAMS Workshop
Makerere University
September, 2010

2. Agenda What is a Functional Spec? Specification Template
Technical Goals Exercise
Specification Details
Sample Specification

3. What is a Functional Spec?
A functional specification is a document that describes the essential technical requirements of a system or feature, including the procedures by which it can be determined that requirements have been met.
Specs are helpful in a number of ways:
Enable teams to achieve consensus on what a program is to achieve before implementing it
Allow for accurate estimates for work and resources
Act as a negotiation and reference document for engineering changes
Help avoid duplication and inconsistencies
What
In systems engineering a specification is a document that clearly and accurately describes the essential technical requirements for items, materials, or services including the procedures by which it can be determined that the requirements have been met. Specifications help avoid duplication and inconsistencies, allow for accurate estimates of necessary work and resources, act as a negotiation and reference document for engineering changes, provide documentation of configuration, and allow for consistent communication among those responsible for the eight primary functions of Systems Engineering. They provide a precise idea of the problem to be solved so that they can efficiently design the system and estimate the cost of design alternatives. They provide guidance to testers for verification (qualification) of each technical requirement.[1]
A functional specification does not define the inner workings of the proposed system; it does not include the specification how the system function will be implemented. Instead, it focuses on what various outside agents (people using the program, computer peripherals, or other computers, for example) might "observe" when interacting with the system. A typical functional specification might state the following:
When the user clicks the OK button, the dialog is closed and the focus is returned to the main window in the state it was in before this dialog was displayed. Such a requirement describes an interaction between an external agent (the user) and the software system. When the user provides input to the system by clicking the OK button, the program responds (or should respond) by closing the dialog window containing the OK button.
It can be informal, in which case it can be considered as a blueprint or user manual from a developer point of view, or formal, in which case it has a definite meaning defined in mathematical or programmatic terms. In practice, most successful specifications are written to understand and fine-tune applications that were already well-developed, although safety-critical software systems are often carefully specified prior to application development. Specifications are most important for external interfaces that must remain stable.
Purpose
There are many purposes for functional specifications. One of the primary purposes on team projects is to achieve some form of team consensus on what the program is to achieve before making the more time-consuming effort of writing source code and test cases, followed by a period of debugging. Typically, such consensus is reached after one or more reviews by the stakeholders on the project at hand after having negotiated a cost-effective way to achieve the requirements the software needs to fulfill.

4. Standard Spec Template
Overview
Goals/Non-Goals
Scenarios
Functional Design
Add sections here as appropriate
Implementation Plan
Deployment Plan
Security
Performance
Implementation Details
Open Issues
Written by either program manager or business stakeholder – background on what the feature is and why we need it. Sometimes called a “one-page spec”.
Written by program manager in collaboration with developer. Describes what will be built in enough detail to unblock the dev team, including user interface design, workflows, and system diagrams.
At MSFT, we sometimes write the one-page specs before we make the final decisions on which features we will implement. The one pagers help us understand the features a little better so we can make good decisions.
Written by developer, discusses deeper technical aspects of system
Written by spec owner, should be empty when spec is “done”

5. Users of a Functional Spec
Business Stakeholder
Provides and/or reviews goals, scope, scenarios
Program Manager
Usually the primary author
Interfaces with the business stakeholder for goals
Works with developers on functional design
Developer
Authors implementation sections
Writes code and test cases to validate functional design
Test Engineer
Ensures scenarios function as described in the spec
Operations Manager
Consumes the deployment plan

6. Spec may be updated at each stage of development
Spec Lifecycle
Gather Requirements
Overview, Goals, Scenarios
Design the System
Functional Design
Implement the System
Implementation Details
Quality Assurance & Documentation
Validate scenarios against implementation
Operate & Maintain
Deployment Plan
Capture customer feedback
Spec may be updated at each stage of development
Unifying document for all disciplines

7. Overview What is the feature about and why do we care?
You only need a few paragraphs to describe it at a high level
But make them compelling, especially if the feature is large or expensive to build
Address the business need for the feature
Anyone (technical or otherwise) should be able to read this section and understand it
Tic-tac-toe is a game for two players, X and O, who alternate marking spaces in a 3x3 grid with their symbol. The player who successfully places a set of three marks in a horizontal, vertical, or diagonal row wins the game. If no player can create a horizontal, vertical, or diagonal row then the game is a draw. Player X goes first. As it has a simple set of rules, tic tac toe provides leisure entertainment for people of all ages.

8. Goals and Non-Goals
Goals and Non-Goals clearly articulate what you are and are not doing
Goals are the concrete outcomes you are trying to accomplish with the feature
They should be prioritized
Non-Goals help with scoping: they clearly identify things you are not trying to accomplish
Non-goals may (or may not) become goals at a later point in the project

9. Technical Goal-Writing Exercise
Tic-Tac-Toe
A two-player game where players try to get three squares in a row
Beyond that high-level description, what is it and, more importantly, what isn’t it?
Goals
[P1] Support two human players in a game that is run as a client application
[P2] Support custom player names …
Goals
[P1] Support two human players in a game that is run as a client application
[P1] Use a graphical representation of the players and game board
[P1] Alternating turns between the players starting with X
[P1] Declare a winner when a player has successfully placed three marks in a row
[P1] Declare a tie when no player can make a winning move
[P2] Allow the game to be run inside a web-browser
[P2] Use multi-colored graphics in the game visuals
[P2] Support custom player names
[P2] Tabulate, store, and display statistics on players’ performance
[P3] Add a timer to limit the amount of time a player is allowed to spend on a turn
[P3] Allow for the two players to be on separate machines and play through the network
[P3] Have one player be a computer-based (AI) player
[P3] Allow player O to start a game
Non-Goals
Support for any grids larger than 3x3
Support for non-grid shaped game boards
Animation of game play
Non-Goals
Support for any grids larger than 3x3 …

10. Tic-Tac-Toe Goals and Non-Goals
[P1] Support two human players in a game that is run as a client application
[P1] Use a graphical representation of the players and game board
[P1] Alternate turns between the players starting with X
[P1] Declare a winner when a player has successfully placed three marks in a row
[P1] Declare a tie when no player can make a winning move
[P1] Support for starting a new game after the initial game has completed
[P2] Allow the game to be run inside a web-browser
[P2] Use multi-colored graphics in the game visuals
[P2] Support custom player names
[P2] Tabulate, store, and display statistics on players’ performance
[P3] Add a timer to limit the amount of time a player is allowed to spend on a turn
[P3] Allow for the two players to be on separate machines and play through the network
[P3] Have one player be a computer-based (AI) player
Non-Goals
Support for any grids larger than 3x3
Support for non-grid shaped game boards
Animation of game play
Allow player O to start a game

11. Scenarios
A scenario is a narrative description of a user’s interaction with the system
There is usually at least one scenario for each type of user who interacts with the system
Richard has an afternoon free. He calls up his friend Joseph and invites him over to play tic-tac-toe. Richard launches tic-tac-toe and a 3x3 grid appears on the screen. They play a game, Joseph connects three Os on the right-most column and is declared the winner.

12. Functional Design
Describes the system in enough detail for testers to write test plans and developers to design the implementation
Description of major components
Application workflows/logic
User Interface mockups
Database schema
Protocols/wire formats for any client/server interactions
Diagrams are helpful
Does not cover details that are purely internal implementation
Focuses on what outside agents observe when interacting with the system

13. Switch Current Player and update UI
Player clicks a square
Is square available?
Yes No
Update Gameboard
Switch Current Player and update UI
3 in a row?
Yes No
Start New Game
Print winning message
Tie?
Yes No
Print tie message
Update Statistics

14. Functional Design: Security
A spec for any security-sensitive feature needs to address security
Discuss concerns and mitigations
Priority
Security Concern
Mitigation 2
If we decide to implement a web-based version of the game, then we need to account for denial of service attacks.
Add encryption (https) and HTTP authentication

15. Functional Design: Implementation & Deployment Plan
Implementation Plan
Gameboard and game-play logic
UI design and visuals for gameboard, players, and winner notifications
Hooking up the UI gestures to the game-play logic
Advanced features, such as customized player names, timing moves, and showing high scores
Implementation Plan
If applicable, what are the different phases involved in the development of the feature?
Especially important for complex features that will take more than a day or two
Deployment Plan
How will we deploy this new feature? Are there updates or patches that need to be installed on a server? Any database schema changes?
Does the order of steps matter?
Deployment Plan
Tic-tac-toe will be packaged as a single Windows executable. There are no features that require special setup tasks.
If my feature required client updates, my deployment plan would be longer

16. Implementation Details
Further details on how the developer will implement the product
Algorithms
Class/method definitions
Data structures
Enables testers to perform deeper testing
For bigger features, allows for better collaboration among multiple developers

17. Open Issues
Used to capture unanswered questions during the spec authoring and review process
This section should be empty when the feature is complete
Open Issues
Should we use Windows Forms or WPF for the UI?
Should we secure the high-score file, or at least obfuscate it?

18. Sample Specification
The functional specification for Tic-Tac-Toe is included in your Student Packet