Agile Troubleshooting: Interface Documentation

ArgonDigital - enterprise automation experts

Share This Post

When an organization first switches to agile, the documentation and proper vetting of interfaces can often be a significant roadblock to successful delivery. In my own project, I have seen this borne out several times over. No more—I am seeking to properly detail data requirements in sufficient time. I have seen too many blown deadlines and late-breaking defects. Most data issues arise from one of three scenarios: metadata, undocumented data requirements, and tribal data knowledge. If your agile project deals with multiple data interlocks, check out these common problem areas below.


The devil is in the details, so the cliché goes. Unfortunately, this is no less true for agile data projects than it is for waterfall data projects. The metadata hidden in interfaces creates a huge challenge for an agile BA to document in a timely and efficient manner. There is no substitute for crisp, clean interface documentation with as much metadata present as possible. My suggestion is to find a good data viewing tool, such as Visual Studio or XML Spy, and break metadata documentation down into discrete workable chunks.

While developing data-heavy features, this rigorous data documentation has saved me from countless hours of defect review and rework. It is so very preferable to uncover mismatches in nullability, data types, and cardinality for data objects in a grooming session compared to a defect review meeting. To borrow another cliché, a stitch in time saves nine.

Undocumented Data Requirements

As frustrating as it is, there are times when data documentation is lacking for a particular interface. You cannot change the fact that a system or service has little in the way of usable information to stem data issues. In these instances, your best bet is old fashioned human interaction. Working with a developer with domain knowledge or another BA assigned to the system or group is the only way around this particular impediment.

I’d also suggest internalizing the frustration that you feel with undocumented systems. If you have bandwidth, consider creating the documentation. It may not be enough to speed your project along, but it will certainly help future projects avoid these same pitfalls.

Tribal Data Knowledge

In large organizations, it is simply not practical for people to have specific domain knowledge for a large number of systems. Certainly these people exist, but it is likely their time is scarce. In most organizations, you must go through gatekeepers of information—tribal subject matter experts. These bottlenecks of information can sink project timelines. My best advice here is to plan accordingly. If data requirements for a system or user group are not well-documented and in-person elicitation is required, plan for this in sprint planning.

To some extent, you get dealt your hand for some interlocks. Equipping yourself with the knowledge that tribal knowledge takes time to disseminate can help set expectations. The amount of time saved in the long run is well-worth the extra effort to make sure data is flowing smoothly between interfaces.

More To Explore