IAM Agile Part 3: Working Software over Comprehensive Documentation

Brian Weigel, Senior Consultant, SecureITsource, Inc.

Welcome back to our discussion of Agile development in Identity and Access Management programs! If you missed the second article, it can be found here. Today, we will be talking about the second tenet of the Agile Manifesto – ‘Working Software over Comprehensive Documentation’. Again, all feedback is welcome and encouraged!

As mentioned in the previous article, these tenants are phrased in a somewhat adversarial context (X over Y). This is not meant to imply that Y has no value or use, just that X should be prioritized higher. The general interpretation should be ‘You should always do X to the extent possible, and only do Y if the situation calls for it or if Y better enables X.’ As we move onward, we will start by looking at the items on the right, then the items on the left, and finally how they can be balanced in a healthy Agile organization.

Working Software

‘Working Software’ – what exactly does this mean? How we define this phrase makes a world of difference in the success or failure of any software development or implementation effort, so let’s begin by breaking this phrase down into its components.

We will start with ‘software’ in this effort, as it is something that permeates our digital world to such a degree that most people already have a fundamental understanding of what software is. At the most basic level, software is what controls how a computer changes from one state to another and execute instructions with the goal of performing some action. From the latest social media app on your smartphone to the diagnostic and monitoring tools maintaining our power and communications infrastructure, software is what enables us to effectively use the technology that is powering our world.

More than just taking inputs and returning outputs through a seemingly mystical maze of ones and zeroes, software also includes some much more personable aspects. User interfaces and user experiences are a major component of software, as well as documentation on both use and maintenance (more on this later). This leads us to discussing the other component – ‘working’.

What does it mean to say that something is working? Is simply saying that it is producing the expected result enough? How much do ease of use and the overall user experience matter? Where does reliably and availability factor in?     Before we start picking into these nuances, let’s first state the obvious – the foundation of ‘working software’ is the standard ‘if I do X, then Y happens.’ Given a known set of conditions and process, if I feed this application a given input, I will get an expected result, and this is consistently repeatable.

This implies a certain degree of reliability in that the process itself works consistently and as expected. But that is not all there is to being ‘reliable’. If we feed it inputs outside of its expected parameters, how will it react? Will it handle it gracefully or will the system crash? Can we leverage these unexpected inputs to reveal information that we do not want to expose? Having good QA resources available to help design and execute test cases is invaluable.

Comprehensive Documentation

Documentation is a core component of any system or application. Users need to know how to properly use a system, administrators need to know how to properly check and maintain the system, and developers need to know how the application is built and runs so that they can make appropriate updates over the lifetime of the system. The problem is that all this documentation can take a considerable amount of time and effort to compile.

We never want to completely neglect documentation for these reasons, but in our fast-paced world, speed of delivery is a key driver in a project’s time-to-value prospect and can make-or-break an organization’s competitive edge. It is not uncommon for multiple organizations to be working on similar products, and it’s often the first to bring it to market that becomes the leader in that field, so the desire for thorough documentation should be carefully weighed in this regard.

In many cases, such as the example above, it may be desirable to release software with limited documentation to expedite delivery. This can certainly help the organization maintain a competitive edge and begin realizing value from the development activities, which is always a win. The caveat is that, with this approach, documentation often starts taking a back seat to development activities, and any documentation that may be created can become inaccurate or outdated if not maintained.

This risk is partly mitigated by the fact that Agile development encourages open lines of communication between the development team and end users, but should not be seen as a long-term replacement for appropriate documentation for long-term sustainability. To summarize the intent of this tenant, it is acceptable (and often desirable) to sacrifice comprehensive documentation in favor of optimizing the time-to-value of a project, but under no circumstances should thorough and appropriate documentation be neglected entirely for long-term sustainability.