In a situation where good quality specifications already exist, it can be beneficial to reuse them in a well planned manner.
This is often the case for an industry like automotive, in which OEMs want to leverage existing standards so that not every requirement needs to be written uniquely.
(As suppliers know, there are more than enough unique requirements ;-) Obviously this is done all the time - consider for example requirements on the basic bolts and nuts of a physical assembly. It would almost always be done referencing a standard, which in turn includes the requirements for the structural integrity and strength of the steel they are made of.
We see this also in software/functional requirements:
for: OEM requirements →(referencing) → Standards →(referencing) → other standards
This makes up a kind of hierarchy of documents similar to an upstream/downstream situation in open-source software projects. These document will range from general (upstream, open standards) to specific (downstream / OEM requirement specification).
When we can't use a specification 100% as written, a delta-specification is needed. There are several options:
Suggest modifications first to the original specification ("upstream first" principle)
Forking the original specification into a new variant
Writing a new specification from scratch- Writing a meta-specification clarifying the applicability of the main specification. If we are significantly modifying or adding requirements, we might rather call it a delta-specification.
Upstream Modification
The theoretically ideal approach is to affect the upstream to include our requirements. There may be trade-offs however. The time it takes to convince other stakeholders and to get a new specification released could be prohibitive. A specification might also become a "kitchen sink" if it tries to be everything for everyone.
For these reasons it might not always be appropriate to modify the original specification.
Forking
Forking is usually not a great approach because it causes a disconnect, despite that much of the information is and should be the same. This disconnect causes the projects to drift apart and the effort of "keeping up to date" increases.
- Several aspects to consider
- License conditions must allow it, of course
- Good citizen / good behavior
- Avoid any confusion between versions
- → This rarely a good approach!
If it's done, using best-practices for software is recommended (such as keep the specification in plain text-format and use a git repository). But even with this it's very difficult to keep a specification from becoming contradictory or illogical. There are no compilers and automated unit-tests to check your modified work...
Applicability matrix / delta specification
Very often a good compromise is the applicability matrix approach - or if slightly more differences are expected writing a delta-specification.
This is a very useful way to create a formal specification that fits exactly to ones needs, while avoiding proliferation of multiple overlapping documents. It is a kind of "meta-specification" that is one level above and refers to the others. (*Normally a "meta-specification" probably means a specification that defines how specifications should be written, so the name delta (difference) -specification seems appropriate).
Delta Specification format
When creating a specification by referencing existing ones we should consider the following:?
- Reuse parts of the specification as a whole and rewrite others
- Reuse with references and modifications
- Only parts of the general specification might be applicable. Modify referenced specifications by an applicability list or matrix.
still meeting these goals:- Completeness
- Avoiding ambiguity
- Clarify how to handle conflicts and inconsistencies. (What takes precedence)
- Finally, add unique requirements in a way that is not too difficult to manage.
- When referring to a combination of multiple documents, it can lead to ambiguity or at least making the consumption of the specification very difficult and impractical.
Principles:
- Each chapter should define the requirements by minimal repetition, by referring to already written text
- Sometimes, for clarity some copying/repetition is however desired, overriding rule 1. Consider both the convenience of specification writers/maintainers and that of the consumers of the specification.
- Modifications can be done by adding additional text that slightly changes what the original spec requires. This still avoids repeating a lot of the major work that went into the original.
- In particular consider that things like "optional", "conditional" and "mandatory" can be modified.
example:
Automotive Virtual Platform Specification, version x
1. Introduction
Purpose, Scope, goals, context, applicability...
2. Architecture
Assumptions made about the architecture, use-cases.
Limits to applicability, etc.
3. General requirements
Automotive requirements to be met (general)
3. Virtual Device Requirements
3.1 Serial Device
3.1.1 Standard Serial Device
REQ-1: Follow chapter x.y in [VIRTIO]
3.1.2 Network device exposed as serial device
For this special type there are some additional requirements.
REQ-2: The virtual device MUST provide an auxiliary programming interface (e.g. ioctl on POSIX) with the following feature:
- .... blah
3.2 Block Device
REQ-3: Follow chapter 4.5.6 in [VIRTIO] and chapter 4.2.1 in [Other spec]
REQ-4: When applying REQ-3, if there are conflicting requirements (note: disk performance, chapter 4.9.9), the requirement in [Other spec] shall take precedence.
REQ-5: Device type Foo, listed as optional, shall here be mandatory.
REQ-6: Device type Bar, listed as mandatory shall here be conditional: