Writing software requirements specifications

When I started in business application development, my wrong believing was that some general software requirements specification format can be applied to all kinds of business systems.

My research

I was looking for widely applicable standards, trying to:

  • Generalize integrator’s specification formats, that was successfully applied to customize business systems in which integrator specializes (and I was encountered).
  • Adopt national standards like GOST (Russian).
  • Adopt international standards like ISO.

Here I mean, I was researching for my own format, that I could give an analyst or use myself to standardize analysis work.

These attempts happened with me a lot of times, I would say constantly.

Frequently, when I started to describe something to be developed, the particular situation made irrelevant a lot of parts of previously used formats (as well as GOST and ISO standards) because:

  1. Different systems use different terminology (that is used by users and developers).
  2. In a customization project, it makes no sense to write requirements that are inherent to the existing / purchased system. Every system determines its own zones where you have to make decisions (while other zones are closed to change so you have nothing to describe).
  3. For better time and cost estimation, things that are specific and important should not be missed by developers due to the large size of the specification, describing everything in a standard format.

Even if I had software requirements specification format, that I could apply to the system by excluding and adopting its parts, it didn’t mean that any analyst could do it as well (practice has shown, I can’t expect it). For me, it means how much important analyst’s experience is.

Finally, there are very few things, that could be standardized. Let’s talk about them.

Top level

Let’s classify software requirement specifications with 2 characteristics: (a) the level and (b) the kind of a specification.

In terms of the level there are:

  1. High-level specifications, that allow you to start talking with developers. Those are enough if you have (an internal) development team, deeply skilled in company technical and business context.
  2. Detailed specifications, that are highly recommended, when you hire an external team or consistently rotate developers.

Different specification kinds are:

  1. Specifying modifications in a purchased or existing system.
  2. Describing completely new software to build.
  3. Specifying exchange formats.

It’s nice to have a top-level document, describing which existing systems will be touched and what software would be developed. It’s necessary for big solutions and is named “architectural document”.

The structure of documents I tend to have in a project is like:

  1. Business requirements (top level).
  2. Architectural document – no details, just overview.
  3. Specifications.

The order in the list above is the same as the natural order of birth of those documents in a project.

By the project roles, the authors of those documents are:

  1. Business analyst for business requirements.
  2. IT architect for an architectural document.
  3. System analysts or software architects for specifications.

That’s all you can classify at the top level.

Specification level

A simple specification may contain sections:

1. Introduction.
2. Definitions.
3. Non-functional requirements.
4. Functional requirements.

Detailed specification for a new software may include (my schema):

1. Introduction.
2. Definitions.
3. Non-functional requirements. It may include:
3.1. Runtime environment.
3.2. Managing source code.
3.3. Back-end requirements.
3.4. Front-end requirements.
3.5. Integration principles.
3.6. Logging and telemetry.
4. Access control and audit. It includes:
4.1. Authentication and authorization.
4.2. Permissions and roles.
4.3. Audit.
5. User interface.
5.1. Conception.
5.2. Sections and screen forms.
5.2.x. <Section name>
5.2.x.1. Section view.
5.2.x.2. Entity view.
5.2.x.3. Entity editing.
6. Model
6.x. Object <Object Name>
6.x.1. Properties.
6.x.2. Requirements.
6.x. Enumeration <Enum Name>
7. Periodic jobs.
8. Integration procedures.
9. Reports.

The introduction must be verbose if an external team works on a project, describing the context and key ideas of a software product.

The largest parts of a specification usually are 5 and 6. Instead of ‘x’ you substitute new number for every new UI section (in part 5) or object / enum (in part 6).

Properties in 6.x.1 usually are described in the form of a table, having columns for the name, type and description of the property.

Good examples of requirements for sections 6.x.2 are:

  • The object must support <term from definitions>.
  • On assignment of the value X to property Y do <describe action>.
  • On saving an instance of the object do <describe action>.
  • Property Z is read-only.
  • Combination of values in properties X, Y, Z must be unique among instances of the object in the database.

Basically, requirements of 6.x.2 split into 2 kinds:

  1. Related to object behaviour.
  2. Related to the database.

Requirements related to the behaviour of an object must be unit-testable.

Perhaps, the hardest thing to describe is the user interface. But classic UI section of business software may be described as:

5.2.x.1. Section view.
5.2.x.1.1. Layout.
5.2.x.1.2. Toolbar.
5.2.x.1.3. Filters.
5.2.x.1.4. Registry.
5.2.x.2. Entity view.
5.2.x.2.1. Layout.
5.2.x.2.2. Toolbar.
5.2.x.2.3. Form.
5.2.x.3. Entity editing.
5.2.x.3.1. Layout.
5.2.x.3.2. Toolbar.
5.2.x.3.3. Form.

Above of the part “5.2. Sections and screen forms” I put “5.1. Conception” illustrating high-level UI layout and describing what is UI section, toolbar, where is the view / editing area.

In case of modifications to purchased or existing software, a specification may vary from containing a flat list of requirements to being similar to the described detailed specification format. It may be:

1. Introduction
2. Definitions
3. Model changes
3.x. Object <Object Name>
3.x.1. Properties.
3.x.2. Requirements.
3.x. Enumeration <Enum Name>
4. Periodic jobs.
5. Integration procedures.
6. Reports.

In systems that have forms bond to objects (CRUD design) in part “3.x.2. Requirements” I put 3 kinds of the functional requirements:

  1. Related to UI behaviour.
  2. Related to object behaviour.
  3. Related to the database.

Always write exchange format specifications in a separate document, because it is related to at least two systems.

That’s all you can classify at the level of specification.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: