In a situation where good quality specifications already exist, it can be is beneficial to reuse them in a well planned manner, as is the case for the Automotive Virtual Platform definition developed within the HyperVisor project, and the VIRTIO specification.
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
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 surely often be done by referencing a standard, which in turn includes the requirements for the structural integrity and strength of the steel they are made of.
...
This makes up a kind of hierarchy of documents similar to an upstream/downstream situation in open-source software projects. These The document will range from general (upstream, open standards) to more specific (downstream / OEM requirement specification).
When we can't use a specification 100% as written, a delta-specification is neededthe difference needs to be handled. There are several options:
Suggest all 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
- If this is more than an applicability matrix then, we might rather call it a "delta-specification".
Considerations
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 possible to modify the original specification into exactly what is desired.
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 is 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). This is to make maintenance and interaction with the upstream even managable. But even with this it's very difficult to keep that there is a lot of work to keep a combination of "patches" to a specification from becoming contradictory or illogical. There are no compilers and automated unit-tests to check your modified work.../combined work, as is done with software.
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 It has the potential to create a formal short, clear, and unambiguous specification that still 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 Decide which parts of the specification to reuse (by reference) as a whole, and to rewrite othersReuse with references and modifications
- Only some 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.
...
- Each chapter should define the requirements by minimal repetition, by referring to already written text
- Sometimes, for clarity some copying/repetition is however desired for clarity, 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 in the applicability definitions that things like "optional", "conditional" and "mandatory" can be modified compared to the original specification.
...
exampleExample:
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 According to chapter x.y in [VIRTIO].
REQ-1.2: Requirements 4 and 6 in that chapter shall not be implemented.
3.1.2 Network device exposed as serial device
...
REQ-2: The virtual device MUST provide an auxiliary programming interface (e.g. ioctl on POSIX) with the following featurefeatures:
- .... blah
- .... blah
3.2 Block Device
REQ-3: Follow According to chapter 4.5.6 in [VIRTIO] and chapter 45.2.1 in [Other spec]
REQ-43.1: 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-53.2: Device type Foo, listed as optional, shall here be mandatory.
REQ-64: Device type Bar , listed as mandatory described in chapter 1.2.3 in [Other spec], shall here be conditional:conditionally implemented:
a. When implementing a system of type A, Bar is optional.
c. When implementing a system of type B, Bar shall be mandatory.
b. When implementing a system of type C, Bar shall be mandatory with the following modification of chapter 1.2.3
.... blah
...