In a popular online discussion group, the following question was asked: .”how should ICDs (Interface Control Documents) or interface requirements be developed, documented, and managed in an Agile development environment?”.

You can read my views on Agile development and requirements in my blog entitled “Requirements in the Agile World”.  That said, with regard to this question, here are my thoughts:

One description of Agile says: “Agile systems engineering and project management is about ensuring the right information is available to the development team in the right level of detail at the right time so they can build the right product.“

Providing information concerning interfaces is key to the success of a product development project.  This information should include (1) identification of all interactions between your system and the super-system of which it is a part (external interfaces) as well as interactions between the parts that make up your system (internal interfaces); (2) defining and agreeing how the interactions between parts will happen; and (3) communicating the need for all the parts to be designed according to these agreed-to definitions.

For Agile there are two aspects of how this information is managed that need to be considered and addressed within your organizations’ processes: Format and Formality.

Format

What format will you use to document the information noted above? Spreadsheet? Requirement Management Tool? MS Word document? Word of mouth?  If written in a document, what will you call the document? For software you have Application Program Interfaces (APIs) and Software Development Kits (SDKs) that include information on how to interface with the external system with which your system is a part..  It is also common to have a data dictionary that defines how you will communicate data, commands, messages, etc. internally between the parts that make up your system.  So what makes the most sense for your organization?  That is a call that you and your organization can make but know this — the data dictionary needs to be defined at the beginning of the project so all the parts can communicate with each other successfully.  Failing to do this early can result in integration problems later in your project.

Formality 

How formal do you want to manage this information? Does the information  need to be put under formal configuration control or recorded in a document owned, controlled, and managed by the lead person responsible for managing your product development effort?  For some parts, you may decide that because the developers work in close proximity to each other, they can verbally agree on how their two systems will interact with nothing written down and managed.

Perhaps you have figured out by now that there isn’t just one answer.  I recommend that the external interfaces with the customer be written down and managed formally.  This is for your protection as much as it is for the customer’s.  Having the information written down and under formal change control avoids arguments later if the system fails to work when integrated into the larger super system..  Clear documentation helps you avoid the “he said/she said” type of arguments.  A prime example of “he said, she said” is what we have witnessed in the testimony of the Principles working on the HeathCare.gov website!.

For interfaces that are internal to your development team, you can be less formal in your approach.  When communicating a common approach between all parts, it is best to write it down and make the definitions available to all early in your project life.   How formal you are in managing these documents is a personal decision the project lead needs to make.  The lower down the architecture you go, the less formal you can be when developers are co-located.

Managing your interfaces is key to delivering a winning product.

Whatever you decide, it is important that you clearly document your process on how you will manage interfaces and make sure that process is followed.  Poorly managed interfaces is a major reason for integration problems both internally to your project and externally between your product and the super system your product is a part.   Mitigating risks due to interface problems is necessary to delivering a winning product – one that delivers what is needed, within cost and schedule, with the desired quality.

Comments to this blog are welcome.

If you have any other topics you would like addressed in our blog, feel free to let us know via our “Ask the Experts” page and we will do our best to provide a timely response.