<Previous Lesson

Business and Technical English Writing

Next Lesson>

Lesson#30

Writing Specifications and Analysis Reports

In this lecture we will learn:

Introduction:

•In this lecture we will examine types of specifications common to the computer industry.

•Then we will examine the importance and main features of analysis reports.

•We will also see that terms and conventions often differ from company to company, but the

general framework is similar.

Introduction:

•For everyone involved in the design phase of the computer industry – hardware

engineers,software engineers, technicians, and programmers – specifications are the most

important document to be read or written.

•The situation is even worse when work has to be undone or redone because of bad specs.

•Specifications can be categorized into four types:

–Requirement specs

–Functional specs

–Design specs

–Test specs

Requirements specification:

•The result of market research is requirements specifications.

•In it, the marketing people attempt to specify what the market is looking for, what people or

companies who use computers would find useful and would like to have.

•Product definition

–This is as accurate a description as can be written by marketing about the desired product.

–It should answer the question: “What is it?”

•Functions list

–This is a description of what the desired product should be capable of doing.

–It leads to the next type of specification.

•Cost

–This is a ballpark estimate as to what the desired product should cost to be competitive in

the marketplace.

•We then move onto the functional specification.

Functional Specification:

•These specs will form the basis for the highly precise design specifications.

•Hardware functional specifications as a rule contain the following:

Functional description

Configuration specification

Electrical description

Physical characteristics

Standards

Environmental requirements

Diagnostic requirements

Power requirements

Cost target

Maintenance cost target

Resource requirements

Documentation

Risks

Assumptions

Unresolved issues

Glossary

•Software functional specs usually contain the following:

Functional description of the product

Product featuresDependencies

Physical characteristics

Risks

Assumptions

Cost target

Maintenance

Resources

Documentation

Glossary

Design Specification:

•Design specifications are later used as the basis for test plans and user documentation.

•Hardware design specifications generally contain some version of the following

components:

Introduction

Applicable documents

Functional description

External interfaces

Detailed design

Programming considerations

Power requirements

Reliability

Diagnostic considerations

Standards

Environmental requirements

Glossary

• software design specifications should contain the following:

Introduction

Application documents

Functional description

General design

Memory requirements, performance, and restrictions:

Product requirements

Test strategy

Deviations from functional specifications

Interfaces

Glossary

Test Specification:

Introduction

Applicable documents: these documents might describe test procedures on similar

products designed and developed in the past.

Description of unit to be tested

Testing method: this section provides a step-by-step description of the testing procedure.

Precautions

Glossary

Analysis Reports:

•The important thing to remember is that no report format is perfect.

•Company documentation standards attempt to resolve the issue by prescribing a format

into which all analysis reports are poured.

•Report design should be flexible enough to meet a variety of writer purposes and audience

needs.

Title page:

•A title page should be designed with visual order in mind.

•It should be balanced from top to bottom and from left to right.

•It should provide enough information for readers to be able to tell what the context of the

report is and what the report is about.

Abstracts:

•Abstracts are condensation of entire reports, focusing on the main issues: what was done,

what was found out, and its significance.

•Abstracts are self-sufficient.

•The procedure for many companies is to take the abstract from the analysis report, copy it

a number of times, circulate it to readers, and allow readers to order the full report if they

feel like they need the information.

Table of contents:

•The table of contents provide an outline of analysis reports for readers who do not wish to

read the entire report or flip through it looking for the section which contains what they are

looking for.

•It should be made up of headings and subheadings of the report, word-for-word, with the

accompanying page numbers.

List of symbols:

•This is an optional addition to the front matter of an analysis report.

•Include it if you think the readers will need to have symbols defined.

•The same thing applies to the inclusion of a glossary.

Introduction:

•This is the place for the three-part purpose statement introduction.

•It will orient readers to the main issue of the report, to the technical issues or specifics

which are important to the report, and to what the report is intended to accomplish.

Discussion:

•The discussion contains an analysis of the technical issues important to the report.

•It supports the main issue to the report by providing evidence and explanations.

•It should be subdivided into topics, each with a subheading.

Conclusion:

•This section presents the results of the analysis, the evaluation of what was presented in

the discussion.

•Sometimes listing the conclusion is a good way to organize them.

•It calls attention to the conclusion individually, but still enables writers to explain them as is

necessary.

Recommendations:

Recommendations are optional, not all analysis reports have them.•Those reports that do

have recommendations, tell the readers what to do with the information provided in the

report.

Appendix:

Usually this would include derivations of equations, tables of raw data, sample

equations, and so forth.

But the only way to be certain that what is placed in the appendix belongs there is to

assess it within the context of audience needs.

<Previous Lesson

Business and Technical English Writing

Next Lesson>

Home

Lesson Plan

Topics

Go to Top

Copyright © 2008-2013 zainbooks All Rights Reserved
Next Lesson
Previous Lesson
Lesson Plan
Topics
Home
Go to Top