An Interface Control Document (ICD) can be defined as
A document that describes the interface(s) to a system or subsystem. It may describe the inputs and outputs of a single system or the interface between two systems or subsystems.
Within the traditional textual based development process, an ICD was either a text-based document or, a UML type diagram or a combination of the two. Within the MBD development process, it is not entirely clear if additional supporting documentation is required or if the Model can serve as the ICD.
With most topics that I write about I have reached a firm conclusion on what is the accepted best practice. In this area, I still have open questions. In this post, I lay out the pros and cons for using models as ICDs.
Why models are sufficient:
The simplest argument as to why models are sufficient is that the models can be used in place of UML diagrams provided the interface has the sufficent markup. For example in the image below the Simulink Interface View provides the data types and rates of all the inputs and outputs to the system.
When the model is part of a model hierarchy than the calling structure can be derived from the model. (Simulink Model Dependency View)
Why models are lacking:
While the two views above are good, they lack information that is commonly found in ICD documents; the function interface (e.g. the C or C++ calling methods) and the data interface. The models contain and use this information however they do not, natively, display the information. Note: this is a limitation of UML diagrams as also.
The next issue with models as an ICD document is a question of “push and pull.” By having the model as a development artifact and the ICD document you need to implement a change request process.
What can be done?
Use of automatic report generation can augment the information provided natively by the model. Doing this could, in fact, generate a “standard” text-based ICD with the advantage being that the model would stay the single source of truth.
As with most issues in the development where there is not a native tool it is the implementation of a process that helps to bridge the gap. All ready for text-based ICDs people have change request processes in place. The question with an MBD approach is who implements the change at the model, and at the system level?
As always, please feel free to share your thoughts in the comment section.
No question about it, models are supplemental but never suffice for the entirety of interface control. We have to remember WHY we document interface in the first place. It is to control the interface juncture — demarcation point between system boundaries — for some very important reasons. The use of ICD/IRS implies critical need to understand, communicate to stakeholders, and control the interfaces of the system. With this in mind, a picture of the interfaces is worth a 1,000 words, but 10,000 words are needed to sufficiently convey all the salient elements of control for critical systems availability and efficient operations.