Presentation on theme: "Writing Functional Specifications JAMS Workshop Makerere University September, 2010."— Presentation transcript:
Writing Functional Specifications JAMS Workshop Makerere University September, 2010
Agenda What is a Functional Spec? Specification Template Technical Goals Exercise Specification Details Sample Specification
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.
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”
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
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
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.
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
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 1.[P1] Support two human players in a game that is run as a client application 2.[P2] Support custom player names 3.… Non-Goals 1.Support for any grids larger than 3x3 2.…
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 completed 7.[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 network 13.[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
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.
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
Is square available? Player clicks a square No Update Gameboard 3 in a row? Yes Tie? Print winning message Yes No Switch Current Player and update UI No Print tie message Yes Update Statistics Start New Game
Functional Design: Security A spec for any security-sensitive feature needs to address security – Discuss concerns and mitigations PrioritySecurity ConcernMitigation 2If 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
Functional Design: Implementation & Deployment Plan 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? 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 logic 4.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.
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
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 1.Should we use Windows Forms or WPF for the UI? 2.Should we secure the high-score file, or at least obfuscate it?
Sample Specification The functional specification for Tic-Tac-Toe is included in your Student Packet