Technical Guide

2.4 Produce technical guide

The technical guide consists of

  • Project brief
  • Specification document
  • Design document
  • Program code listing
  • Test documentation

Project Brief

This document sets out the general requirements of a client from a system. It is written in non-technical terms and acts as a terms of reference for the programming project team. This document is used as the basis for the creation of the software requirements specification.

Software Requirements Specification

Normally, the project brief for a piece of software, created in conjunction with the client, is not sufficiently precise or detailed enough for implementation. Clients often lack an appreciation of what is feasible or fail to spell out exactly what is required.

The software requirements specification should be agreed with clients and should be a complete statement of the functional and informational requirements of the proposed system. The level of detail of the specification will depend on both the complexity of the system and the development methodology being followed.

The specification should be clear and unambiguous and agreed with the client before future development takes place. Since no system will be completely specified at the beginning of the project, the specification should be written in a form which allows easy amendment.

Formal specification methods and languages exist, but a flexible format would incorporate:

  • Introduction: this will comprise the project brief obtained from the user, ie: the narrative description of the proposed system.
  • Information Description: this will describe the main organisation of data within the system in terms of data structures and their components.
  • Functional Description: a clear description of each function of the system, noting design constraints and performance characteristics.

Design Document

The design document shows the architectural design of the system. Architectural Design is concerned with the overall organisation of a software system. The main idea is to use the subprogram facility available in most high level languages to decompose a problem into simpler sub-problems which can be handled separately. This process is called Functional Decomposition.

Each of the separate software components is called a Module and the process is also known as Modular Design.

Functional decomposition is often described as a Top Down Approach, since we start with the highest level of problem and gradually refine it into greater and greater detail.

The alternative is a Bottom-Up Approach where you start with separate modules and combine them to form a larger software system. Although this is not generally regarded as advisable, it can be useful where you already have existing modules that you want to incorporate into a new system.

Congratulations! You have now reached the end of the Developing Software: Introduction course. Remember, it you need to go back to any of the topics you can do so using the menu at the top of the page.