2 writing functional specifications

8/6/2019 2 Writing Functional Specifications

1/18

Writing Functional Specifications

JAMS Workshop

Makerere UniversitySeptember, 2010


2/18

Agenda

What is a Functional Spec?

Specification Template

Technical Goals Exercise Specification Details

Sample Specification


3/18

What is a Functional Spec?

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

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.


4/18

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.

Written by developer, discusses

deeper technical aspects of system

Written by spec owner, should be

empty when spec is done


5/18

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 casesto validate functionaldesign Test Engineer

Ensures scenarios functionas described in the spec

Operations Manager Consumes the deployment

plan


6/18

Spec Lifecycle

Gather Requirements Overview, Goals, Scenarios

Design the System Functional Design

Implement the System


Quality Assurance &Documentation

Validate scenarios against

implementation

Operate & Maintain Deployment Plan

Capture customer feedback

Spec may beupdated at each

stage of

development


7/18

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 islarge or expensive to build

Address the business need for the feature

Anyone (technical or otherwise) should be able toread this section and understand it

Tic-tac-toe isa game fortwo players, XandO,who alternate marking spacesina 3x3 gridwiththeirsymbol. The playerwho successfullyplacesasetof

three marksinahorizontal, vertical, ordiagonal rowwinsthe game. Ifno

playercancreate ahorizontal, vertical, ordiagonal rowthenthe game isa

draw. Player X goes first. Asithasasimple setof rules,tictac toe provides

leisure entertainmentfor people ofallages.


8/18

Goals and Non-Goals

Goals and Non-Goals clearly articulate what youare and are not doing

Goals are the concrete outcomes you are tryingto accomplish with the feature They should be prioritized

Non-Goals help with scoping: they clearly identifythings you are not trying to accomplish Non-goals may (or may not) become goals at a later

point in the project


9/18

Technical Goal-Writing Exercise

Tic-Tac-Toe

A two-player game where players try to get threesquares in a row

Beyond that high-level description, what is it and,more importantly, what isnt it?

Goals

1. [P1] Support two human players in a

game that is run as a client application2. [P2] Support custom player names

3.

Non-Goals

1. Support for any grids larger than 3x3

2.


10/18

Tic-Tac-Toe Goals and Non-Goals

Goals

1. [P1] Support two human players in a game that is run as a client application

2. [P1] Use a graphical representation of the players and game board

3. [P1] Alternate turns between the players starting with X

4. [P1] Declare a winner when a player has successfully placed three marks in a row

5. [P1] Declare a tie when no player can make a winning move

6. [P1] Support for starting a new game after the initial game has completed7. [P2] Allow the game to be run inside a web-browser

8. [P2] Use multi-colored graphics in the game visuals

9. [P2] Support custom player names

10.[P2] Tabulate, store, and display statistics on players performance

11.[P3] Add a timer to limit the amount of time a player is allowed to spend on a turn

12.[P3] Allow for the two players to be on separate machines and play through the

network13.[P3] Have one player be a computer-based (AI) player

Non-Goals

1. Support for any grids larger than 3x3

2. Support for non-grid shaped game boards

3. Animation of game play

4. Allow player O to start a game


11/18

Scenarios

A scenario is a narrative description of a usersinteraction with the system There is usually at least one scenario for each type of user

who interacts with the system

Richardhasanafternoon free. He callsup his friendJosephandinviteshim overto

playtic-tac-toe. Richardlaunchestic-tac-toe anda 3x3 gridappears onthe screen.

Theyplaya game, Josephconnectsthree Os onthe right-mostcolumnandisdeclared

the winner.


12/18

Functional Design

Describes the system in enough detail for testers towrite test plans and developers to design theimplementation 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/18

Is square

available?

Player clicks a

square

No

Update Gameboard

3 in a

row?

Yes

Tie?

Print winningmessage

Yes No

Switch CurrentPlayer and update UI

No

Print tie message

Yes

Update Statistics

Start New Game


14/18

Functional Design: Security

A spec for any security-sensitive feature needsto 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/18

Functional Design: Implementation &

Deployment Plan Implementation Plan

If applicable, what are thedifferent phases involved in thedevelopment of the feature?

Especially important for complexfeatures that will take more thana day or two

Deployment Plan How will we deploy this new

feature? Are there updates orpatches that need to be installedon a server? Any databaseschema changes?

Does the order of steps matter?

Implementation Plan

1. Gameboard and game-play logic

2. UI design and visuals for gameboard,

players, and winner notifications

3. Hooking up the UI gestures to the

game-play logic4. Advanced features, such as customized

player names, timing moves, and

showing high scores

Deployment Plan

Tic-tac-toe will be packaged as a single

Windows executable. There are no

features that require special setup tasks.


16/18


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/18

Open Issues

Used to capture unanswered questions during

the spec authoring and review process

This section should be empty when thefeature is complete

Open Issues

1. Should we use Windows Forms or WPF for the UI?2. Should we secure the high-score file, or at least obfuscate it?


18/18

Sample Specification

The functional specification for Tic-Tac-Toe is

included in your Student Packet

http://lawolf.net/jams/Student%20Packet.doc

2 writing functional specifications

Documents