Documenting Interfaces
Documenting interfaces has always been a challenge. We put the interface requirements in a separate document and give that as a part of the documentation to the groups designing on both sides of the interface. Now I have a single document with all aspects of the interface neatly covered, but when I look at my system requirements, I am missing some aspects that are hidden away in various interface specifications. It would be nice to have all my environmental requirements in one place, all my physical requirements in one place and so on. For complicated interfaces, perhaps a separate document is a good idea, but for simple interfaces, I think there is a better way.
The need to be sure of giving the same information to both sides of the interface means that we have worked with these separate requirements specs. I see an alternative reality.
Working in Rational DOORS Next Generation, I can have an interface requirements specification in a module, with all of the requirements tidily partitioned away. However, I can reuse (not copy) those requirements in system, or subsystem requirements modules. That is kind of nice, but there is more value to be had.
I can look at the interface requirements and see where they are reused. If an interface requirement is only reused in one place then it isn’t much of an interface! … or possibly it is an interface to something outside of our responsibility. I can look at an interface requirement from within a system requirements spec and see where it is reused. This leads me to the other side of the interface, and gives options of negotiation. I am able to see the associated tests, the associated design and other linked information, and have the source data, not an unmanaged copy. When I look at an interface requirement, if I see it is used in many places then I need to be very cautious about making changes.
Many interfaces are layered, either using the OSI model, or something different. There are interfaces between the layers as well as the end-to-end interfaces. An interface specification will often contain multiple layers, and a designer will often be working with a single layer at a time. By reusing the interface requirements across system, or subsystem, requirement specifications, only the relevant requirements are included, and the need to wade through lengthy documentation to find the few key paragraphs is removed.
(Reposted from http://ukhazel.com/wp/documenting-interfaces/)
Hazel Woodcock, I like how you are leveraging the knowledge (data) withing the database to get out of 'document centric' perspectives and into 'model centric' realities. However, when one has interfaces to a black box (not internally view-able) system, it typically is impossible (due to security restrictions) to see the tests, design item evidence, risks (failure modes), other requirements, etc. of that system as you stated. A solid data model with dynamic security (view rights based on where I 'started' navigating the data model with full view rights) might be appropriate in this case, to enable knowledge communication while minimizing administration overhead (to grant access rights, etc.). Having fields on those objects that are 'public' and 'private' would also be needed to enable effective awareness of those objects or data types.