Technical writing/Requirements and Functional Specifications EE

back to Technical Writing at Wikiversity

Course aims

This course aims to improve the way that Business Analysts, Developers, Project and Product Managers:

• Interact with each other by understanding each other’s roles
• Identify and understand the initial objectives (Goals) of the Customer
• Actively guide the customer to discover further details of the Goals until no detail is missing
• Accurately record and track the Goals to the end of the project
• Translate the Goals into workable Requirements with the help of a team of Experts

From the start of the process the development team only work on productive elements of the project.

The team of Experts will map the Requirements to Functions.

Pre-requisites:

• A good standard of English (English version)
• Good communication skills

The Target Audience includes

• Business (System) Analysts
• Product or Project Managers
• Assistants to the above
• Solution System Architects
• Hardware and Software Developers

Requirement Specification Overview

It is important that all pieces of information (including all conversations with the customer) are recorded at the time they occur. Often at the end of the project disputes happen between the customer and supplier that can result in lengthy negotiations or even litigation (in the law courts). Details that seem minor at the time can be a big problem later. The more structured and retrievable these notes are the better. It is recommended that these records are stored in a way that all the Project Development team can access them. Examples are to store the information as:

• Tasks in a task tracking system such as a Customer Support System CSS or Team Foundation Server TFS
• Chunks in a Wiki based database such as Confluence.

Manually tracking requires a rigid set of numbering rules

Feasibility study

Before the development of requirements phase there is a feasibility study or analysis of the concepts involved in the new product. If the feasibility study is positive then the team will develop Requirements into detailed Functions and Structures. The feasibility study will analyse whether:

• There are sound business cases for each of the Goals
• There is sufficient budget to complete the project
• The project will make a profit
• There are sufficient resources

The purpose of the feasibility study is to stop projects that can never make a profit before money and resources are wasted.

The Requirements phase

The Requirements phase may be broken down into the following stages:

• Discover Goals (gather the initial requirements from Customers and record them)
• Analyse (check that the requirements are consistent and complete)
• Define (record descriptive requirements for developers)
• Specify (create a link between requirements and design)

Requirements Form the Basis of the Final Contract

Do not begin to develop the project before knowing exactly what the Goals and needs of the Customer are. If the real Goals of the Customer are not satisfied, then the final product will not satisfy the needs of the customer. Example: The Customer for this document was the Training department. The training department set the goals in the Course aims.

Write full and complete Requirements because the Requirements will form the basis of the Contract with the Customer. Do not leave out any details. Details that appear to be minor at the start of the contract can create problems later. The Requirements do not state how the system performs the functions that are required. The Solution Architect decides how to implement the functions with the Project Team.

Contracts are written to a tight deadline with many last minute alterations. Give the Contract department a solid basis to write the contract from.

Pre course Exercise 1 Make a label for a bottle of Beer

The Exercise aim is to show how much information is required in a simple project and how difficult it is to predict a customer’s true goals without proper information.

Write all the information that you think is required in the white space on the bottle label for a new product called Pilgrim Beer.

You have no information so you will have to assume what is needed.

Definitions of Requirements, Customers and Goals

A Requirement:

• Describes and defines a single aspect of an objective (Goal) that a particular product or service must have or do.
• Becomes an input to the design stage of product development.

Example: A Requirement of this course is to keep the language simple.

A Customer is: a person or organisation with goals that pays for the project.

Example: The Customer for this training is the Training Department

A Goal is an objective that the Customer wants to achieve in the project.

Example: The Goals of this training are stated in the course aims

Tell the Customer if any Goals are unachievable early in the process

The next module is

The Roles of the Development Team (EE)