The Language of Technical Writing – How to communicate your idea

Language of Technical Writing

How to communicate your ideas

Project Name: Methodology & Processes

Project Code: METHPROC

Version: 1.0

Author: Marc Dimmick

Position: System Business Analysis

Phone: (08) 6217 6335

Email: marc.dimmick@dcp.wa.gov.au

1.

Process & Procedure Project

Page 8

[Company] Page 11 of 11 Language of Technical Writing

The Language of Technical Writing – How to communicate your idea

document history

Version Responsible Date Notes

1.0 Marc Dimmick 01 Apr 06 Initial Document

*** End of
Revision
List ***

1. Contact for Enquiries and Proposed Changes

If you have any questions about this document contact:
Name: Marc Dimmick
Designation: System Business Analysis
Phone: (08) 6218 6335
Email: Marc.Dimmick@dcp.wa.gov.au

Table of Content
1 document history 2
1.1 Contact for Enquiries and Proposed Changes 2

2 Writing User Requirements (BR) 4

3 Business Requirement (BR) 5
4 What Should be Included in BR? 6
4.1 Identify and Link Requirements with Sources 6
4.2 Establish Business Rules for Contingencies and Responsibilities 7
4.3 Establish a Requirements Traceability Matrix 7
4.4 What Should I Know about Writing BR’s? 8
4.5 10 language quality characteristics 8
4.6 Imperatives: 9
4.6.1 Words and phrases that command the presence of some feature, function, or deliverable. 9
4.7 Continuances: 9
4.7.1 Phrases that follow an imperative and introduce the specification of requirements at a lower level. 9

Process & Procedure Project

Page 8

[Company] Page 11 of 11 Language of Technical Writing

The Language of Technical Writing – How to communicate your idea
4.8 Directives: 10
4.8.1 Categories of words and phrases that point out illustrative information within the BR. 10
4.9 Options: 10
4.9.1 A category of words that provide latitude in satisfying the BR statements that contain them. 10
4.10 Weak phrases: 10
4.10.1 A category of clauses that can create uncertainty and MULTIPLE or SUBJECTIVE interpretation.10
4.11 Text Structure: 11
4.12 Specification Depth: 11
4.13 Readability Statistics: 12
4.14 Conclusion 12

2.

Process & Procedure Project

Page 8

[Company] Page 11 of 11 Language of Technical Writing

The Language of Technical Writing – How to communicate your idea

Writing User Requirements (BR)

3. This document will describe what a BR’s document is and why it's important, and discuss the
critical elements for writing BR. Although this document does not try to address all aspects of
developing BR, it aims to help you settle the scope for such a project, to provide some guidelines
for writing BR. We hope with this information, you'll not be asking, "Why me?" but proclaiming "Why
not me?"

Process & Procedure Project

Page 8

[Company] Page 11 of 11 Language of Technical Writing

The Language of Technical Writing – How to communicate your idea

Business Requirement (BR)

BR’s are an organisation's understanding (in writing) of a customer or potential client's needs and
dependencies at a particular point in time (usually) before any development work. It's a two-way
insurance policy that assures that both the client and the organisation understand the other's needs
from that perspective at a given point in time.

The BR document itself states in precise and clear language those functions and capabilities a software
system must provide, as well as states any required constraints by which the system must abide. The
BR also works as a guide for completing a project with as little cost growth as possible. The BR is often
referred to as the "parent" document because all following project management documents, such as
solution design, statements of work, software architecture specifications, testing and validation plans,
and documentation plans, are related to it.

The BR contains functional and non-functional needs only. It doesn't offer design suggestions, possible
solutions to technology or business issues. It should only be what the development team understands
the customer's system requirements to be.

1. A well-designed and written BR performs four major goals:

It provides feedback to the customer. A BR is the customer's assurance the development organisation
understands the issues or problems to be solved and the software behaviour necessary to address
those problems. Therefore, the BR should be written in natural and unambiguous language rather than
formal language. It may include charts, tables, data flow diagrams, decision tables.

It breaks up the problem into component parts. The simple act of writing down software requirements in
a well-designed format organises information, places borders around the problem, solidifies ideas, and
helps break down the problem into it’s component parts in an orderly fashion.

It serves as an input to the design specification. As mentioned previously, the BR serves as the parent
document to resulting documents, such as the solution design specification and statement of work.
Therefore, the BR must contain enough detail in the functional system requirements so a solution
design can be devised.

It serves as a product confirmation check. The BR also serves as the parent document for testing and
confirmation strategies that will be applied to the requirements for verification.

4. BR’s are typically developed during the first stages of "Design Cycle," which is the first product
cycle in which information is gathered about what requirements are needed--and not. This
information-gathering stage can include onsite visits, questionnaires, surveys, interviews, and
perhaps a return-on-investment (ROI) analysis or needs analysis of the customer or client's current
business environment. The specification, then, is written after the requirements have been gathered
and analysed.

Process & Procedure Project

Page 8

[Company] Page 11 of 11 Language of Technical Writing

The Language of Technical Writing – How to communicate your idea

What Should be Included in BR?

You probably will be a member of the BR team (if not, ask to be), which means BR development will be
a collaborative effort for a particular project. In these cases, your company will have developed BR’s
before, so you should have examples (and, likely, the company's BR template) to use.

● Executive Summary

● Introduction

1. Purpose

2. Scope

3. Assumptions, dependencies and constraints

4. Process improvements

5. Gap analysis summary

6. Actors

7. Glossary

8. Related documents

● Detailed Requirements

● Testing Strategy

● Appendix A: Data Conversion Requirements

But, how do these general topics translate into an BR document? What, specifically, does an BR
document include? How is it structured? And how do you get started? An BR document typically
includes four ingredients, as discussed in the following sections:

A template

A method for identifying requirements and linking sources

Business operation rules

A traceability matrix

9. Identify and Link Requirements with Sources

As noted earlier, the BR’s serve to define the functional and non-functional needs of the product.
Functional requirements each have an origin from which they came. Be it a use case (which is used in
system analysis to identify, clarify, and organise system requirements. This will consist of a set of
possible sequences of interactions between systems and users in a particular environment and related

Process & Procedure Project

Page 8

[Company] Page 11 of 11 Language of Technical Writing

The Language of Technical Writing – How to communicate your idea
to a particular goal), government control, industry standard, or a business need. In developing BR’s, you
need to identify these origins and link them to their matching needs. Such a practice not only justifies
the requirement, but it also helps assure project stakeholders that trivial or false needs are kept out of
the specification.

To link requirements with their sources, each requirement included in the BR should be labelled with a
unique identifier that can remain valid overtime as requirements are added, deleted, or changed. Such a
labelling system helps preserve change-record integrity while also serving as an identification system
for gathering metrics. You can begin a separate needs identification list that ties a business requirement
identification (BRID) number with a description of the requirement. Eventually, that requirement ID and
description become part of the BR itself and then part of the Solution Design and the Requirements
Traceability Matrix, discussed in following paragraphs. The table below explains how the Solutions
Design and BR ingredients work together.

TABLE: User Requirement Identification Number

BRID BR Para Requirement Description/Comments
17 5.1.4.1 Requirements 1 Solution Design
18 5.1.4.1 Requirements 2 Solution Design
19 5.1.4.1 Requirements 3 Solution Design
20 5.1.4.2 Requirements 4 Data Conversion

10. Establish Business Rules for Contingencies and

Responsibilities
"The best-laid plans of mice and men..." begins the famous saying. It has direct application to writing
BR’s because even the most thought-out requirements are not immune to changes in industry, market,
or government controls. A top-quality BR should include plans for planned and unplanned
contingencies, as well as a clear definition of the responsibilities of each party, should a contingency be
implemented.

Some business rules are easier to work around than others, when Plan B has to be invoked. For
example, if a customer wants to change a requirement that is tied to a government control, it may not be
ethical or legal to be following "the spirit of the law." Many government regulations, as business rules,
simply don't allow any compromise or "wiggle room." A project manager may be responsible for
ensuring that a government regulation is followed as it relates to a project requirement; however, if a
contingency is required, then the responsibility for that requirement may shift from the project manager
to a regulatory attorney. The BR’s should anticipate such actions to the furthest extent possible.

11. Establish a Requirements Traceability Matrix

The business rules for contingencies and responsibilities can be defined clearly within a Requirements
Traceability Matrix (RTM), or contained in a separate document and referenced in the matrix, as the
example in Table above. Such a practice leaves no doubt about responsibilities and actions under
certain conditions as they occur during the product-development phase.

The RTM functions as a "chain of custody" document for needs and can include pointers to links from
requirements to sources, as well as pointers to business rules. For example, any given requirement

Process & Procedure Project

Page 8

[Company] Page 11 of 11 Language of Technical Writing

The Language of Technical Writing – How to communicate your idea
must be traced back to a mentioned need, be it a use case, business essential, industry-recognised
standard, or government regulation. As mentioned previously, linking requirements with sources
minimises or even erases the presence of false or trivial requirements that lack any justification. The
RTM is another record of common understanding, but also helps during the development cycle.

As software design and development advance, the design and the code must be tied back to the
requirement(s) that define them. The RTM is completed as development progresses; it can't be
completed earlier (see Table 3).

12. What Should I Know about Writing BR’s?

Unlike formal language that allows developers and designers some latitude, the natural language of
BR’s must be exact, without ambiguity. It must be precise because the solution design, statement of
work, and other project documents are what drive developing the final product. That final product must
be tested and confirmed against the design and original requirements. Specification language that
allows for interpretation of key requirements will not yield a satisfactory final product and will likely lead
to cost overruns, extended schedules, and missed deliverable deadlines.

13. 10 language quality characteristics

Quality What It Means

Characteristic
Complete BR’s defines precisely all the go-live situations that will be faced and the system's ability to address
them.
Consistent BR’s capability functions and performance levels are compatible, and the needed quality features
(security, reliability,.) do not deny those capability functions. For example, the only electric hedge
trimmer that is safe is one that is stored in a box and not connected to any electrical cords or outlets.
Accurate BR’s should precisely define the system's ability in a real-world environment, as well as how it
interfaces and interacts with it. This aspect of requirements is a significant problem area for many
BR’s.
Modifiable The logical, hierarchical structure of the BR’s should simplify any necessary adjustments (grouping
related issues together and separating them from unrelated issues makes the BR’s easier to change).
Ranked Individual requirements of an BR’s are hierarchically arranged according to stability, security,
perceived ease and difficulty of implementation, or other feature that helps in the design of that and
following documents.
Testable A BR’s must be stated in such a manner that unambiguous assessment (pass and fail or some
quantitative measure) can be drawn from the BR’s itself.
Traceable Each requirement must be uniquely identified to a source (use case, government requirement,
industry standard,.)
Unambiguous BR’s must contain statements that can be interpreted in one way only. This is another area that
creates significant problems for BR’s development because of the use of natural language.
Valid A valid user need is one in which all parties and project participants can understand, analyse, accept,
or approve it. This is one of the main reasons BR’s are written using natural language.
Verifiable A verifiable user requirement is consistent from one level of abstraction to another. Most attributes of
a specification are subjective and a definite assessment of quality requires a technical review by
domain experts. Using indicators of strength and weakness provide some evidence that preferred
attributes are or are not present.

14. Imperatives:

Process & Procedure Project

Page 8

[Company] Page 11 of 11 Language of Technical Writing

 The Language of Technical Writing – How to communicate your idea
1. Words and phrases that command the presence of some feature,
function, or deliverable.
● They are listed below in decreasing order of strength.
Shall Used to dictate the provision of a functional capability.
Must or must not Most often used to show performance need or constraints.
Is required to Used as an imperative in a statements when written in passive voice.
Are applicable Used to include, by reference, standards, or other documentation as an addition to the
requirement being mentioned.
Responsible for Used as an imperative in BR’s that are written for systems with predefined architectures.
Will Used to cite things the operational or development environment is to provide to the
capability being mentioned. For example, The vehicle's exhaust system will-power the
ABC widget.
Should Not used often as an imperative in BR’s statements; however, when used, the user
requirement statement always reads weak. Avoid using Should in your BR’s.

15. Continuances:

1. Phrases that follow an imperative and introduce the specification of

requirements at a lower level.
There is a correlation with the frequency of use of continuances and BR organization and structure, up
to a point. Excessive use of continuances often shows a complex, detailed BR. The continuances below
are listed in decreasing order of use within BRs. Use continuances in your BRs, but balance the
frequency with the fitting level of detail called for in the BR.

● Below:

● As follows:

● Following:

● Listed:

● In particular:

● Support:

16. Directives:

1. Categories of words and phrases that point out illustrative information

within the BR.
A high ratio of total number of directives to total text line count correlate with how precisely requirements
are specified within the BR. The directives below are listed in decreasing order of instance within BRs.
Incorporate the use of directives in your BRs.

Figure

Process & Procedure Project

Page 8

[Company] Page 11 of 11 Language of Technical Writing

 The Language of Technical Writing – How to communicate your idea
Table

For example

Note

17. Options:

1. A category of words that provide latitude in satisfying the BR

statements that contain them.
This category of words loosens the BR, reduces the client's control over the final product, and allows for
possible cost and schedule risks. You should avoid using them in your BR. The choices below are listed
in the order:

● Can

● May

● Optionally

18. Weak phrases:

1. A category of clauses that can create uncertainty and MULTIPLE or

SUBJECTIVE interpretation.
The total number of weak phrases found in an BR suggests the relative ambiguity and incompleteness
of an BR. The weak phrases below are listed alphabetically.
Adequate be able to easy provide for
as a minimum be capable of effective timely
as applicable but not limited to if possible tbd
as appropriate capability of if practical
at a minimum capability to normal

19. Text Structure:

Related to the number of statement identifiers found at each hierarchical level of the BR and point out
the document's organisation, consistency, and level of detail. The most detailed BRs were nine levels
deep. High-level BRs were rarely more than four levels deep. BRs believed well organized and a
consistent level of detail had text structures resembling pyramids (few level 1 headings but each lower
level having more numbered statements than the level above it). Hour-glass-shaped text structures
(many level 1 headings, few a midlevels, and many at lower levels) usually contain a greater amount of
introductory and administrative information. Diamond-shaped text structures (pyramid shape followed by
decreasing statement counts at levels below the pyramid) indicated that subjects introduced at higher
levels were addressed at various levels of detail.

Process & Procedure Project

Page 8

[Company] Page 11 of 11 Language of Technical Writing

The Language of Technical Writing – How to communicate your idea
20. Specification Depth:
The number of imperatives found at each of the BR levels of text structure. These numbers include the
count of lower level list items that are introduced at a higher level by an imperative and followed by a
continuance. The numbers provide some insight into how much of the Requirements document was
included in the BR, and can show how concise the BR is in specifying the requirements.

21. Readability Statistics:

Measurements of how easily an adult can read and understand the requirements document. Four
readability statistics are used (calculated by Microsoft Word). While readability statistics provide a
relative quantitative measure, don't sacrifice enough technical depth in your BR for a number.

22. Conclusion
There's so much more we could say about requirements and specifications. Hopefully, this information
will help you get started when you are called upon--or step up--to help the development team. Writing
top-quality requirements specifications begins with a complete definition of customer requirements.

Coupled with a natural language that incorporates strength and weakness quality indicators--not to
mention the adoption of a good BR template technical communications professionals well-trained in
requirements gathering, template design, and natural language use are in the best position to create
and add value to such critical project documentation.

Process & Procedure Project

Page 8

[Company] Page 11 of 11 Language of Technical Writing