Talk:Interface control document

ICD references

Norm, I'm afraid I don't really understand the relevance of the references you've provided for the ICD article. The first (from a quick glance) doesn't seem to talk about ICDs at all; the second talks about ICDs within the context of a particular simulation architecture; the third critiques the windows API; the last indicates that ICDs are often incomplete, but can be made better using UML. None of the references appear to provide any support for the assertion that

It should be noted, that ICDs are absolutely necessary where subsystems are developed asynchronously in time; [emph mine]

and likewise for the assertion that

otherwise, it may be impossible to ensure proper development of complementary interfaces for intercommunicating subsystems.

Am I missing something in these articles? If so, can you please direct me to the parts of the articles in question that do support the above assertions? Thanks. --Allan McInnes (talk) 04:11, 10 May 2006 (UTC)

In the absence of the development team for an interfacing process, the ICD serves as the interface requirements document for the (second) team. If any process is sufficiently complex, all interfaces will need to be documented for future maintenance and/or for upgrade/replacement of interfacing systems, else how can a future engineer be sure that s/he has correctly satisfied all communications protocols and not missed or misinterpreted any? BTW, a documented API is an ICD.

[1] is primarily a list of references for collaborative/cooperative projects. Further exploration would reveal that most required the use of an ICD in order to facilitate communication about a common interface between projects.

Quoting from the main reference, "This paper describes a fairly straightforward exercise in collaborative engineering using the Web to enhance communication and documentation between project partners.

"Although the descriptions of the development of the seeker and the MADE tools are superficial, the authors' goal is to illuminate necessary tools, problems, and future directions for collaborative engineering."

Which last included ICDs.

[2] "One benefit [of the architectural approach, including ICDs] is that resulting simulations are interoperable and evolvable to accommodate technological and methodological advances in hardware and software.

"In most general terms, the PIU works the following way. A set of data definitions and a set of routing rules for a vehicle are defined and captured in an Interface Control Document (ICD).

"Changes to the ICD Table and piuComm header file are agreed upon by the team. The team members, including both TARDEC engineers and government contractors located off-site, independently update their processes from the agreed-upon interface specifications. The PIU developer uses the steps given in the PIU Maintenance Guide to tailor the PIU for the change. A suite of documents has been developed to support the maintenance process [includes the ICD table][16].

"Currently, if a developer wants to develop a mobility model that can participate in a VSF simulation, it must be PIU compliant. This means that it must first fully define its interaction with its environment. This is completely and unambiguously specified in the ICD Table and piuComm.h++ header file. It must then link in the correct version of the PIU, instantiate a piuComm object, and perform the sends and receives expected of it by the other processes."

[3] This paper documents some of the problems in generating an apropriate ICD (in this case an API) for future use. As noted,

"Investing one generation of processor power increase in an architectural overhaul of the API will result in a payback in increased programmer productivity, program robustness, and portability worth more than the currently diminishing returns of GUI improvements."

[4] Quoting,

"Often, subsystem teams work independently from one another, developing subsystems from different requirements documents, and using different tools and processes. There is clearly an opportunity for things to go wrong, such as: Limited or delayed communications between subsystem teams can lead to interface problems.

"Subsystems are designed with flexibility in mind so they can be adapted to changing requirements. A focus on encapsulation of implementation details can assist with this, but before committing to a subsystem interface specification, it is important to validate that the interface indeed caters to a variety of uses.

"Mainly, you have to write the subsystem use cases! A project that wants to use a lean process may resist this effort without a strong understanding of the associated benefits. For small subsystems, simply defining the interface and generating diagrams depicting how the interface should be used is often sufficient.

"When different teams or organizations are responsible for different subsystems, interface misunderstandings can arise and even result in contractual arguments. One way to avoid such problems1 is to separate interface components from the implementation of the subsystems [e.g., via a ICD], and have only one team design and implement these components. A related concept is the Interface Control Working Group (ICWG), a group of people representing the development teams impacted by the interface.

"If you use a common visual notation such as UML to define interfaces and the exchange of information across them, then you will increase joint understanding and reduce ambiguity."

⇒ _normxxx| ^talk ⇒ email 00:09, 11 May 2006 (UTC)

I'm not disputing that ICDs are useful. I understand what they are, and how they're used. What I'm looking for is support for the assertion that they are "absolutely necessary" (i.e. there's no other way to achieve the same effect, and everyone agrees that ICDs are necessary). Based on what you're quoted and highlighted above:

• Ref. 1 doesn't support this assertion at all, except possibly by inference (which would violate WP:NOR)
• Ref. 2 provides anecdotal evidence that ICDs can be used to ensure interface compatibility between teams, but that doesn't provide evidence that they must.
• Ref. 3 again suggests that ICDs can be used...
• Ref. 4 explicitly states that "One way to avoid such problems is to separate interface components from the implementation of the subsystems [e.g., via a ICD]"
• I note also that Ref. 4 flat-out states that in "large systems" ICDs are likely to be incomplete and ambiguous.

Based on those references, I'd suggest revising the assertion in question to read something like:

ICDs are often used where subsystems are developed asynchronously in time, since they provide a structured way to communicate information about subsystems interfaces between different subsystem design teams.

--Allan McInnes (talk) 02:36, 11 May 2006 (UTC)

Check out the revised wording. You are not likely to get a flat out assertion, such as I made, except in a text, which is hard to search for on the web. (Check out your SE books; I gave mine away.) ⇒ _normxxx| ^talk ⇒ email 00:47, 12 May 2006 (UTC)

Acronyms

The acronyms of SIRS and HIRS are completely unqualified and should be expressed explicitely before being used. — Preceding unsigned comment added by 202.153.214.99 (talk) 22:23, 1 February 2021 (UTC)

SIRS/HIRS and Wikipedia mention

> The inputs and outputs of a single system, documented in individual SIRS[software interface requirements specifications] and HIRS[hardware interface requirements specifications] documents, would fall under "The Wikipedia Interface Control Document."

why is "Wikipedia" mentioned in that phrase?

Criticism section

This section seems largely copied from the referenced source (see copypaste) tag in article. I propose removing this section entirely, as "criticism" of a specific document within a technical domain is not really relevant to the discussion of such a document. Closetsingle (talk) 21:06, 6 November 2024 (UTC)