Information Technology Reference
In-Depth Information
For the most part this section should be in simple written English, but it is
unavoidable that some jargon and diagrams will be required to convey concepts.
These sections should be explained thoroughly in the literature as these documents
are the primary insight by stakeholders into the development process.
13.2.1 Specification Documentation
Specification documentation comes in many forms; different documentation is
required for each of the seven sections listed above. Some sections will require
object diagrams or use case diagrams, while other sections will require carefully
written documentation.
The systems overview section should be a brief overview of functionality,
compatibility and project timeline. Basically, this should be an overview of any-
thing that you may want to know about the project. For this reason it should not be
dense or convoluted with many diagrams and flow charts, but be brief and concise.
The most important points it should cover are:
• Development cycle description: who will do what, where and when.
• What actual project deliverables should encompass.
• Development paradigms that will be employed. Some paradigms that should be
noted in this portion are peer programming, object oriented, model driven
architecture and service oriented architecture. The list is almost infinite.
• Platform requirements, which includes whether the project will require multi-
platform development tools or will only be targeted at one system.
The most important aspect of a user may be how they will interact with the final
product. The user interface section should cover this in detail. For this section it is
very appropriate to use mock ups of the interface as well as written descriptions.
Mock ups of user interfaces should do more than show an image, but should have
callouts and highlights of the most important features.
The functional description is needed to develop use cases and process flow
diagrams. Functional descriptions can easily become highly technical. They are
undoubtedly one of the most technically intense portions of the design document.
To combat this, the use of diagrams showing flow control can be used as well as
simple walkthroughs of scenarios.
The non-functional description should cover the important aspects of the pro-
ject that are unique and special. Many times the form of comments, efficiency,
overhead and other similar aspects should be covered in this section. This section,
however, should not be brought down in quality with a huge increase in length
with overly ambiguous statements about ''ample comments'' or ''optimal effi-
ciency''. Instead, it should set specific guidelines for many of the non-functional
aspects. Guidelines should be testable and when appropriate, the test used to
measure them should be described as well.
