Technical Specification

When a change to the applications reach the level that a functional design is required then a technical design may also be required.

When to do them?

A technical specification is required for all significant new development. Other issues should be accompanied by a technical specification if the changes the issue required were significant enough to merit a functional design. A technical specification can also be required for other reasons, and your supervisor will advise you if one is required for a given task. A good general guideline is to ask yourself “Is this complex enough that another developer would have difficulty following what is going to be done without a document?”

A technical specification is generally not required for bug fixes.

What goes into them?

There is no written in stone outline of what must go into a technical specification. There is a template for the specification located on the internal share point portal, but that is meant as a starting place. You should include enough detail in your technical specification so that if you were to no longer be available, another developer could successfully implement it.

Template

The template for the technical specification is located on the Artsman file server in the TM Development/TM Design Documents folder and is called AMS Design Template.doc. Documents are to be named ‘yymmdd .doc’ and a history retained in the TM Development/TM Design Documents folder.

Optional elements

The template is meant to be an example or a guideline to the way a technical specification might appear. Sections may be deleted as needed or rearranged as necessary.

Peer Review

Once a technical specification is complete you must have a peer review before implementing the proposed changes. This peer review is not to judge the quality of the developers work, but the quality of the proposed solution as well as its compatibility with other areas of the system. A proposal that might be absolutely perfect for one area can completely destroy functionality in another if it is not compatible.

Methods

The peer review need not be in person. Copies of the technical specification can be emailed to participants with revision tracking turned on and then reviewed as they come back one at a time.

Persons involved

A good technical specification review will include other developers that can critique the methods and code that are going to be used. Design and SQA can benefit from the information as well, but are not a required part of the review process.

Security Concerns

Sensitive areas of the application including, but not necessarily limited to, any protected classes should have limited peer review. This review should include the developer and one member of the Architecture team.