How to Read a Functional Specification
Often a member of a technical team is given a software functional specification and instructed, “read this,” without any guidance or instructions. On the other extreme a member of a software development team is given the task, “document the functions of our application” without a clear understanding what is meant.
By understanding how to read a functional specification you can learn to glean the necessary information from the document and then learn how to communicate to improve the document. But even more important by understanding how to read functional specification you can begin to learn how to write better functional specifications.
Over the past several years, I have worked with organizations around the globe. Without a doubt there is a lack of ability to read and analysis functional specifications. I have read 1000’s of functional specifications some were written well, but the far majorities are poorly written. Functional specifications are often incomplete or even contradictory. Even within a single project comparing & contrasting one functional specification with other functional specifications is a nearly impossible task. Different terms are used, different writing styles are adopted and in most cases the documents include different sections.
Often functional specifications are not written with the reader in mind. That is, who is going to read this document and what are they going to use it for. It does not matter what method of documentation is used whether it is Use Case, Traditional, Rational Rose, or whatever.
As you read a functional specification or for that matter any technical document, it is important to take notes, make marks on the document and actively ask questions. There are basically three levels or reading: elementary, inspectional and analytical. Most of us are use to reading novels, newspapers or magazines at an elementary (enjoyment level) and not reading at an inspectional level or analytical level.
The point of a functional specification is to communicate functional information (logical information) regarding how a software application behaves. In particular a functional specification needs to be able to describe in very concise manner how a user interacts with the application. The reader of a functional specification needs to be able to inspect the document for completeness and be able to analysis the contents of the document.
As you begin to read the functional specifications you should ask yourself, why am I reading this document, what is it that I want to learn? If you are providing feedback on the document then your level of reading will be at the inspectional level. Is the document complete or are there things missing? Inspectional reading needs to be the type of reading that takes place prior to a formal review of the document.
If you plan on taking the functional specification into the next phase (design and analysis) of the software lifecycle, then your level of reading needs to be at an analytical level. That is, you need to be able to understand the document at a very low level of detail. You need to be able to understand the flow of information.
Finally a functional specification describes how things are to be not how they should be. The author needs to be describing the right way of doing something; or that one way is better than another way.
Obtain an Overall Understanding
First you need to decide the level in which you intend to read the document. You need to decide if you are going to read the document from an inspectional perspective or read the document from an analytical perspective.
Before you begin to read the functional specification (or any technical document) in some depth, you should review all the sections and get an overall idea of the document. In fact, I would recommend you do that with this document.
Standard Set of Questions
As you read a functional specification you need to be able to answer the following questions. If you are reading from an inspectional perspective you need to answer the inspectional questions. If you are reading from an analytical perspective you need to ask both inspectional and analytical questions.
· Does the title of the functional specification make logical sense?
· Does the numbering scheme of the functional specification tell me anything about the functional specification?
· Are the Functional Specifications numbered in a logical sequence or are they randomly stored in a directory?
· Are all the major sections labeled with a title that is logical?
· Is the document organized in a logical sequencing of events?
· If comparing two or more functional specifications are they titled, numbered, and organized in a consistent manner?
· If diagrams are present do they describe the same series of events as the text of the document?
· Is there a glossary in the document? Is it complete?
· Is there consistent usage of terms within the document?
· If comparing two or more functional specifications is there a consistent usage of terms in all the documents?
· Is there a comprehensive listing of all functional specifications that are referenced.
· Is there a master cross-reference that shows the inter-relationships of all specifications?
· What is the state of the application when the functional specification begins?
· How is the information being processed?
· Does the author describe the workflow?
· Are the transaction logical groupings of information – a single event? Does the transaction describe single event or is it multiple events within one transaction.
· Is the information going to be stored in files?
· Is the information coming from outside to inside the application?
· Is the information coming from inside to outside the application?
· Is the information going to be entered by a user or an electronic feed from another application?
· Does retrieved information need to be processed beyond retrieval; does it contain derived data (calculations, algorithms, etc.)?
· Are all the algorithms and calculations described?
· What functionality is self-evident, but not described by the author?
· Can the requirement be verified?
· Are business scenarios and examples consistent with the workflow.
· What is the state of the application when the functional specification terminates?
Comparing Multi-Functional Specifications
Like most software projects there will be several functional specifications. Each functional specification needs to be read as a stand-alone document, and then the functional specifications need to be understood as they relate and reference other functional specifications. Therefore, all functional specifications need to be organized and written in a consistent manner. To fully understand the entire software application you will need to make several passes through all the functional specifications comparing the specifications as you go.
In the absence of a number sequence it becomes very difficult to find a document and reference that document. Imagine a public library that contains hundreds of documents with no logical numbering scheme or organization. If the author or authors have created numerous functional specifications they need to have number sequence.
Logical sequences of events
The information flow of a functional specification should be in a logical manner and make sense. For example, if the author was describing the creating and update of information there is a logical flow of information.
1) Before information is updated it must be retrieved.
2) Before information is retrieved it must be created.
Therefore, the logical sequence of information is Created, Retrieved, and Updated. Since Deleted follows the same sequence as updated, then deleted can be added to the list of items also.
This is only one example, the workflow describe in a functional specification needs to follow a logical sequence of events.
Does this functional specification use any features provided by other functional specifications? If so, then functional specification needs to be referenced.
How to provide critical comments
As you read a document it is important to be able to provide comments. An organized document is easier to review and provide comments than a disorganized document.
Hopefully, the specification has been written in a numbered bullet point format. As you provide comments you can write and reference the specific bullet. In the attached example, you could easily reference a particular section and number; hence, the author would know exactly the part of the document you were referring to. Additionally, numbering makes traceablity possible. Traceability becomes a benefit when tracking functional specifications through the entire software lifecycle.
It is important that you are specific in your comments. Perhaps the author writes the information is calculated automatically. Instead of writing, “I don’t understand what you mean,” write, “What is the equation for the calculation?”
You describe that the data is going to be maintained, but the data is never retrieved. Where does the data come from?
You describe first that the data will be updated, but first the data needs to be created and retrieved.
The title of a functional specification should describe in a very concise manner what is the functional purpose of the specification. Instead of creating a title of Maintain Customer Information, the following would be more concise.
a) Maintain Customer Address Information
b) Maintain Customer Invoice Information
Since many of the functions are shared between Create, Update, Read and Delete (CRUD). Then they should be combined within one functional specification and called Maintain.
Distinguishing between vocabulary and terminology.
Every field of knowledge has its own special vocabulary and software is no different. Technical writers are notorious for having private vocabularies. Using the same word over and over is awkward and boring for an author of a novel or story. Often authors of technical documentation substitute different words having the same or very often similar meanings for important words in their text. This is just opposite of what their writing style needs to be.
Does the author use multiple terms to describe a single event? For example, does the author mix the terms update, change and modify? Does the author intermix terms like input and enter? If so, the author needs to choose only one term and be consistent with this term.
Every time the author changes words (shifting his terms), you as a reader need to do the same. As a reader you need to conclude if the author is using a different word to mean the exact same exact thing. You need to ask the author, if the terms (or words) mean exactly the same thing or if the author is actually describing some other event. Again, if the author is describing the same type of transaction or event the same terms need to be used over again. What seems to be boring writing style for magazines or pleasure reading is a necessity for a functional specification.
Depending on how the phrase is written it may or may not be more ambiguous than a single word or term. This is why a writer is likely to substitute a fairly elaborate phrase for a single word if he wants to be sure that you get his meaning. A functional specification is not the place for an author to write elaborate phrases. Instead the phrases need to be very concise. Instead of a writer inventing new phrases to say the same thing, the same phrase should be used over and over again.
1) Maintain Customer Address Information.
a) Create Customer Address Information
b) Retrieve a list of Customers
c) Select a specific Customer
d) Update Customer Address Information
i) After the customer information is displayed
(1) All information can be updated except Customer Name.
e) Delete Customer Address Information
i) After a particular customer is displayed
All information can be deleted except Customer Name.
1) Maintain Vendor information
a) Create Vendor Information
b) Retrieve a list of Vendors
c) Select a specific Vendor
d) Update Vendor Information
e) Delete Vendor Information.
Of course there needs to be more information, but the point is that the flow of events and the phrases are the same for both Maintain Customer Address Information and Maintain Vendor Information.
Is there a glossary?
Is there a standard glossary of terms that has been defined for all the documentation?
Create – the process of entering or inputting data that did not exist before.
Deleting – the process of removing data from a file that was created previously.
Derived – data that is derived from other retrieved information.
Dialog – a screen of information that may or may not be multiple transactions.
Edit – the process of insuring that the data is in the correct format. For example, the determination that a zip code is of the correct length or that a phone number is of the correct format.
Entered – information that is entered into specific fields by a user via some online screen input.
Get – information comes from another application. That is, another application maintains the information.
Maintain – the process of creating, updating or deleting information on a file.
Retrieve – information comes from inside the application. That is, other transaction within my application maintains the information.
Saved – the action or event that invokes maintaining.
Transactions – a transaction is data in motion. A transaction can be a Create, Get, Retrieve, View, Update, and Delete.
Update – the process of changing or modifying data that was created previously.
Validate – the process of insuring that the data correct.
View – information that is retrieved but is not going to maintained.
Example Functional Specification Layout
Title: 475 - Calculate Overtime and Regular Pay For Specific Employees.
Calculate regular and overtime pay for employees.
Assumptions (or Pre Conditions):
A dialog is opened.
1) The employee is selected from a retrieved list of all employees
2) The total number of hours worked during the past week is entered for each the employee.
3) The total number of regular hours is calculated.
4) The total number of overtime hours (if applicable) is calculated.
5) The regular pay is calculated.
6) The total overtime pay (if applicable) is calculated and displayed.
7) All information is saved.
8) Once information is saved it cannot be modified via this process. See Functional Specification Maintain Adjustments to Payroll.
The overtime pay is calculated as follows
Examples (Business Scenarios)
Referenced Functional Specifications (Secondary Use Cases)
By understanding how to read a functional specification you can begin to write better functional specifications, provide better comments to authors of functional specifications, and understand functional specifications better. By developing better functional specifications you can improve your overall software process. Perhaps there is nothing that gets the biggest bang for the buck than good functional specifications.
By the way, we should not forget the whole point of a software application is to take user requirements and create automated processes. Often as software professionals we forget that we are developing software for a client. It is critical that those needs of a client be organized and consolidated.