Corporate Training Magazine

Documenting Success: The Art of Writing Software Specifications
Vol 2 Issue 3- May 2006

By Mary Nasi

Specification documents that outline software design are extremely important for the flow and promotion of business. A well-prepared document is useful for programming, marketing, and fundraising purposes because it acts like a technical business plan that identifies the original intent of the project and outlines the scope of the design. This type of documentation reduces the opportunity for misunderstandings between the client and the service-company and promotes clarity amongst the departments involved with the project.

Unfortunately, many software companies neglect to spend the appropriate time required to make this type of document useful to anyone. In fact, some neglect to produce the document at all. Many databases end up looking like a patchwork quilt that is held together with Band-Aids because the structural foundations have been taken apart and rebuilt, many times, due to lack of proper planning and guidance. Although users may not see the effects of this chaos, programmers can encounter permanent problems with maintaining the software and limitations with transferring the work to other projects, not to mention the amount of time wasted correcting unnecessary mistakes.

When creating a specifications document, consider the following elements:

People
You need to ensure that the appropriate people attend the software-design meetings. These people include at least one lead member of each type of team involved with the project. Aside from the client, there should also be someone from marketing, management, technical support, and perhaps documentation.

The client builds a verbal picture of the dream. At the first meeting, everybody should just listen and make notes. At this critical time, service company people often jump to conclusions about what is wanted before the client has finished with their description, and mistakes are often made,. The service company should only challenge the original vision at later meetings when technical data are present to support their statements for changing a feature.

The marketing person builds confidence in the client about the company's abilities and creates strategies about how this project can define future opportunities. These elements become important in the presentation of the project to the public and reflect the company's image or style. Once a project has started, the marketing person usually communicates with the clients about general status issues.

The management representative or project manager creates a hardcopy outline that reflects the client's vision and the company''s profile. This outline defines the process and stages of development required to bring the client's dream into reality. The management person also oversees the development of each stage and sets the time limits for the project. The project manager should communicate with the client about project details or modifications.

The technical person determines whether the dream is possible with the existing technology and can sometimes produce the first draft of the specification document. Rarely does the technical person address the client directly because their focus is at different levels, which can lead to personality clashes.

The documentation coordinator is required when you need a specifications document that accommodates both technical and non-technical people. Clarity amongst the different departments and with a client increases your chances of success with the project.

Each person in the team plays a role in the project and, therefore, needs to be informed of decisions that affect the specifications document and the software creation or scope.

Language
The specifications document should indicate the type of terminology used for GUI items and for the variable names in the programs. It is not necessary to list each word, just indicate when the language used is standard to a particular industry.

There is a tendency in many companies to create 'unique' language within the programming group to identify variables. Sometimes, this leads to an explosion of variable names that extends into the GUI labels, which creates havoc with the users. It is counter-productive to change the wording for an industry that already has a technical language. Remember that the product should serve the client first and use language appropriate for the intended industry and country.

Culture
Be aware of your client's corporate or international culture. There may be political issues dealing with status or security that need to be addressed. Certainly in international environments, the status or level of authority is important and may require additional efforts on GUI's to make items appear more important or more intellectual, more (or less) colorful, even more complicated. Although these efforts seem trivial at times, remember that the political arena often affects funding, so be careful not to dismiss an item that exists for a personality bias.

Content
Your specifications document should include the following sections:

Client Section
In this section, describe the client's vision and then indicate how it is feasible. Append to this description as the client or company refines and modifies the goals of the project.

Marketing Section
This paragraph defines the company image and identifies the client (technical or non-technical and culture) so developers know the standards to follow and the look-and-feel of the final product. This is useful for GUI layout, language, and flow.

Technical Section
Describe what elements are technically possible and which ones may be difficult to achieve (the reality check). Also, include the details about database design, library structure, networking and security. If there are areas of concern, then enter any recommendations for alternate possibilities.

Project Manager Section
Describe the processes to achieve the desired result. Include flow charts of the development stages and provide a time-schedule for completion to the first evaluation.

Accounting Section
Outline the costs involved to produce the project described by the client. This section may force a reconsideration of the project scope, which affects all other sections.

Time
Allow at least a month to create the first draft of your specification document. The first client meeting and subsequent brainstorming sessions could take a week. In the second week, refine the ideas, check with the client where necessary, and complete any research. Take another week to produce a draft of the document and get internal opinions using simple mock-ups for database design and GUI structure. In the fourth week, meet with the client and present the completed draft for their approval, identify the areas of concern and produce the refined specification document. Both parties get a copy.

Note: Some companies and projects require more/less time to create the specifications document. The point is, create a proper one, so no time is wasted.

As you encounter problems with the design/project, make the necessary changes, adjust the document, inform the client, sign off and move forward.

Using a specification document, you can build a solid foundation in the software, avoid band-aid fixes, and get the assignment right the first time.

Mary Nasi is s senior writer, consultant and training strategist with Isan Communications Incorporated.