Define Functionality | IIS 6: The Complete Reference

The goal of defining the functionality is to determine enough detail from the owner's perspective to define a successful outcome for the solution. Following are the goals of the define functionality step:

Determine the way the desired solution should exist and function so that a developer with limited expertise could produce a solution without having to ask the owner any further questions or seek further clarification.
Establish an expectation with the owner as to what will be received from the effort in terms of how the solution will exist and function on delivery and when it will be delivered.
Reestablish an estimate for the amount of work that needs to be completed and the expected delivery date for the solution.
Obtain the owner's acceptance of how the solution will exist and function on delivery and when it will be delivered.

As described previously, the way a solution exists and functions is the functional requirement for the solution. Since the interpretation of the phrase 'the way a solution exists and functions' is given to great creative license, you need to narrow the scope of the functionality to the context of the solution. Asking the owner the following questions should help provide answers to clarify the functional requirements relative to a web-based solution:

How will the solution be hosted? The solution might need to be hosted at the owner's site or on a third-party's site. The platform (operating system, web server, or other portal enhancement product) might already be chosen or required for use with the solution that needs to be produced. If the owner does not know the answers to this question, then you have to make a recommendation.
What clients need to be served? Web-based solutions do not always support a web browser client. Other means may be necessary to support software solutions that are located elsewhere on the Internet with data that requires processing prior to consumption by an end user. You must identify all of the consumers of data and functionality.
What does the solution need? Web-based solutions might also service other servers elsewhere on the Internet. The solution might be expected to obtain data from another system prior to processing the data. You must identify all of the providers of data and functionality.
Who interacts with the system? The end users should be examined in terms of what they do to the solution and what they need from the solution. What are the roles that exist in the workflow and what responsibilities are associated with the roles?
What real-world entities can be represented in the solution? The object model of the solution must be discovered and documented. The objects in the system and their attributes need to be defined and modeled in total abstraction to the technical constraints of the system. A good strategy is to identify all of the nouns that are used to describe what the solution should do.
What does the solution need to do? Ultimately, the software must do something to data prior to delivering it to a client. The objects identified must have their interactions modeled and documented. After identifying objects in a system by nouns used to describe the system, identifying the verbs in a system can help lead to the understanding of how the objects must interact with each other and thereby describe what actions the objects perform.

In the course of defining the way the solution exists and functions, a great deal of information will be communicated to the owner. Often, the owner is not aware of exactly what they want. The requirements gathering effort is a great opportunity for communicating expectations to the owner by allowing them to arrive at the conclusions themselves. Through the effort of defining the solution, the owner discovers the deliverables and the resources needed to fulfill the solution.

The solution should be documented as it is being defined, in terms of what the owner expects as the outcome. This document is called the functional specification. After the functional specification is complete, the estimate should be reexamined and revised if needed based on the functional specification.

A project plan with milestones and project dates should be specified as part of the functional specification. The owner should be able to review the functional specification and the estimate with the understanding that the work cannot begin until the owner indicates approval, in writing, of the functionality described in the specification. Table 18-2 summarizes the deliverables required for the define functionality step.

Table 18-2: Summary of Deliverables for the Define Functionality Step
Execution Order	Deliverable	Responsible Party
1	Functional specification	Business analyst
2	Qualified estimate for functional requirements	Development
3	Qualified project plan for functional requirements	Project manager
4	Owner acceptance of the defined functional requirements and delivery dates in plan	Project manager

Functional Specification

The functional specification describes the expected outcome from the owner's perspective. This specification is a prerequisite to the technical design and the test scripts, and it serves to define for the owner what will be delivered. It should describe what the solution should do. Owner-visible deliverables should be itemized and described so that a developer with limited expertise could produce the solution without having to ask the owner any further questions or without seeking further clarification. The functional specification should be written from a technically abstracted perspective and should not contain technical instructions for producing the solution. The functional specification also should not contain information about functionality not required by the client, except to describe functionality that is out of scope.

The functional specification, which should be less than 30 pages in length, should provide the following elements:

Identification of every functional requirement so that development and QA can reference parts of the specification in the technical specification and test scripts
Pictures or diagrams for each screen that is referenced or presented to the end user
Change control record
Table of contents
Cover page with owner name and project name
Footer with your company name, confidential info, and print date
Identification of the project with a memorable name

A good way to make each item in a functional specification uniquely identifiable is to number all prose that describes how each part should work. This method works well for describing subordination of functional specifications. Figure 18-4 shows an example of prose in a document that uses hierarchical numbering to identify functional specifications.

click to expand
Figure 18-4: Uniquely identified functional requirements using hierarchical numbering

Making your functional specification 30 pages or less is recommended because it is generally a size that team members can readily review prior to planning and designing. Creating your specification to adhere to an arbitrary size requirement may seem ridiculous. After all, stuffing an elephant into a shoebox will not be possible just because you say that it should. If your set of functional requirements requires more than 30 pages to describe, don't truncate it but, rather, create more than one functional specification so that all of the functional requirements are defined. By having multiple small functional specifications as opposed to a single large functional specification, you are instilling more iterations in your project. The functional specification could be considered the scope of the iterations. The functional specification defines an atomic piece of the project that the owner should be able to relate to or understand.

Development always responds to the functional requirements. By having more iterations of the project, you reduce the length of your development cycle, and shorter development cycles reduce the chance that development will build the solution incorrectly. More iterations for a project also creates more deliverables for the owner to see. An owner typically will have greater satisfaction seeing many positive developments in their project over a given period of time versus a single delivery of the solution. Delivering a project in multiple iterations will also keep the owner occupied with positive project events. If you always deliver functionality when you speak to the owner, you are setting the project's agenda. When a project produces deliverables that the owner cannot see or understand, or if the deliverables occur after long periods of time, the owner tends to speculate negatively about the project's progress.

The front page of the functional specification should convey enough information to tell someone whether or not they need to open and read the document. The owner name, project name, change control section, footer section, and table of contents should all be placed on the cover page of the specification. The owner name and project name clearly indicate the project's origins. The footer section tells the reader which company produced the document, when it was printed, and the fact that this is a confidential document.

The confidential statement has a legitimate legal function if the document is provided to another organization that does not have permission to view the document. When a contract for services is arranged with a software company, the owner is usually asked to honor a nondisclosure agreement that forbids the owner from providing the materials that they receive in the course of the contract execution to another organization. By marking the documents confidential, all recipients may assume some legal responsibility by reading the document if they are not legally entitled. The owner should exercise great care with the distribution of the document and the recipient should understand the confidentiality requirements before reading the document.

A change control section on the front cover should identify the date, an incremented version number, summarized changes made to the document, and who made the change. For an example of a functional specification cover page, see Figure 18-5.

click to expand
Figure 18-5: Sample functional specification cover page

Note

Many word processors such as Microsoft Word or WordPerfect offer a feature to generate a table of contents automatically. It is important that predefined styles be used for the text so that the table of contents generator works properly. For example, the table of contents shown in Figure 18-5 was produced from all Heading 1 and Heading 2 styles. A mistake that many specification authors make is to write an entire document using a word processor and ignore the use of its formatting capabilities.

Note

The Word document used for the sample functional specification is available with the source code on the author's web site.

Developing a functional specification template or common outline is a good way to maintain a consistent approach that will enable all the consumers of the document to know where to look for certain pieces of information based on their knowledge of the last functional specification they examined. The danger in this approach, however, is that you may be destined to make the same failures over and over again.

The best means for striking a balance among the objectives of consistency and providing documentation that meets the needs of the organization is to focus on the spirit of the document's purpose. The template is the default setting, and you should stray from it as required to make the document best describe how the solution should work. If you find that the document template must be changed in the same way for each project, alter the document template. A good outline for the functional specification follows.

Definitions and Acronyms

Define any potentially confusing terms that are used in this document or in the owner's industry.
Define acronyms used throughout the document or in the owner's industry.

This section is helpful in defining terms to avoid confusion and misunderstanding, and it's also useful for establishing a project nomenclature. Names will be used consistently to describe an entity to prevent using multiple terms to refer to the same entity or concept.

Functional Objectives

List all features of the site (avoid too much detail in this section).
List what should be delivered in business terms.

This section is meant to serve as a summary of what the solution will do in terms of the owner. This section is useful for establishing brief terms to represent types of functionality in a given solution that are consistently used by all of the participants in the project. This section should strongly resemble the items identified in the scope document.

Out of Scope

List features that normally belong in the functional objectives section but were removed from the solution.
List features that normally are included in a solution but will not be included in this solution.
List features that seem like they ought to be in this solution.
List features that are not included in this phase of the solution but will appear in a future phase.

This section is the opposite of the functional objectives section, because it lists the functional objectives that are not included in this solution. This section helps to manage the expectations of all those involved in the project so that they understand exactly what the solution won't deliver. Functional objectives cited in the previous section may imply certain things to certain readers. If the reader does not perform a comprehensive examination of the entire functional specification, he or she may not understand the exact meaning of a particular functional objective.

Assumptions

State any new information that would help others understand some of the solution's details that are affecting decision making.

This section allows the specification author to highlight certain situations or conditions that may have been agreed to by the owner. For example, the owner may already have contracted with a graphics art agency for the images that are to be displayed on the site. If these images do not fit in the user interface that is produced while building the solution, the firm creating them will be responsible for changing them to fit as needed.

Affected Screens

List all screens that are part of the solution. These screen names should be used throughout the document.

This section offers a way of naming or identifying all the screens that will be changed or created in the course of completing the solution. One of the most common errors incurred in functional specifications is that they do not make sense in terms of the site's navigational possibilities. Performing the exercise of identifying all othe screens in the beginning reduces this type of failure.

Site Style

Describe the look and feel (font style, browser usage, and window disposition) for the whole site.

This section is optional. Many organizations have a style guide that governs how their site must look and the behavior for responding to certain circumstances or window disposition. For example, the following guide defines a type of window disposition:

Prompting the end user for parameters for a query requires that a new web browser be spawned; otherwise, all content should appear within the same browser that hosts the site navigation. At no time should more than two browser instances remain open for any proper use of the site.

Functional Objective Sections

Describe the functional objectives in detail.
Describe how the functional objective should work from the client's perspective.
Describe compositions of all screens involved in the functional objective.
Describe all possible response scenarios to intended end-user interactions.
Describe exceptions to all possible responses to unintended end-user interactions.

For each functional objective identified in the section Functional Objectives, there should be a functional objective section. This section is devoted to describing each functional objective in detail. It describes the actual business logic for the functional objective to which it pertains, and it describes how the parts of the solution that belong to this functional objective should work from the owner's perspective. Screen flow or process flow should be defined and plotted. A composition for each screen should also be presented. The scenarios for success and failure should be defined. A common failure in functional specifications is the lack of consideration of what should happen under all success or failure events that can occur. Explicitly describing what end-user events are allowed or planned and what the expected results should be will leave little room for failure to identify functionality. For example, a matrix may be assembled that describes the event and the expected solution response to the event, as shown in Figure 18-6.

click to expand
Figure 18-6: Sample functional specification scenarios and exceptions

Appendix

Present use cases.
Present other useful information germane to the project functionality.

The appendix can be thought of as the place for miscellany. If you think that the material is important to the project and that it may need to be referred to by most of the team involved in the project, the material should be placed in the appendix.

Gathering Functional Requirements

To write the functional specification, the author must know the functional requirements. The author must perform a requirements gathering investigation, which involves consulting with the business analyst, who has discussed the solution's functionality with the owner. The success of the investigation is dependent on the disposition of the owner, who may be organized and available to work with the business analyst or uncooperative in providing the necessary information. The business analyst must help the owner focus only on information that is important or useful to the project and not to offer technical details for how the solution should be built.

The business analyst must parse all of the data that the owner provides and assemble a detailed functional specification that describes the solution in a way that satisfies the owner so that the development team can efficiently produce the solution. The analyst must try to identify all the requirements of the software solution, starting from the scope documents.

After the requirements are documented, the use cases of the business processes should be diagrammed using UML. Like many of the other tasks presented in this chapter, the use cases should be produced with as much detail as possible to enable the exact business process to be described. UML diagrams make the use case simple and easy for all to understand and verify.

After the business analyst is satisfied that all of the appropriate use cases have been collected, the use cases should be documented in a form or table so that they may be analyzed. The template or form for documenting a use case should include the following items:

Name of the use case Short descriptive name
ID of the use case Alphanumeric code that is unique
Actors All of the end users who participate in the use case
Preconditions How much of the environment must exist for the use case to take place
Flow What takes place during the use case
Post Conditions What is the environment like after the use case occurs

For example, a use case could be described as follows:

Name: Search Recipe
ID: UC001
Actors: User
Preconditions: User must have successfully logged on to web site.
Flow:
1. User clicks on link 'Search Recipe'
2. Search Recipe screen is displayed in web browser
3. User enters keyword in search keyword dialog box that may be in their desired recipe
4. User presses Enter key
5. Screen is refreshed with results from search
6. If User observes desired recipe name
6.1. User clicks on link to observe recipe
6.2. Recipe is displayed in web browser
7. Else if User does not observe desired recipe
7.1. User enters new search criteria in search keyword dialog box
7.2. User performs search until desired recipe discovered

Post Conditions: User has desired recipe presented in web browser.

This type of analyses is extremely helpful to the design effort. It should be clear that the use case template follows the template of a code function. The Flow section of the use case is an algorithm that may become part of the software that is to be built.

After the use cases are validated by the owner and documented, they may be correlated to the requirements that the owner identified. If use cases are included that do correspond to the requirements, those use cases must either be thrown out or other requirements must be defined according to the particular use cases.

After the functional specification is complete, the estimate and plan presented in the scope step should be revised, if necessary. If changes must be made, supporting functional requirements should be identified that may contribute to the addition of time or expenditure of resources. If the owner agrees to the new schedule, it is time to move on to the next step of the project. If the owner does not agree to the revised schedule, the scope must be altered to make the solution fit the delivery requirement.