Insights >Blog

Being agile doesn’t mean being shortsighted

Miguel D'Amore

June 14th, 2013

A common pitfall of agile software development management that I have frequently found in my experience is that there is no place whatsoever where you can read the entire and updated definition of the specification of the features.

Having pieces of the feature definitions scattered across the different iterations as Stories just because it is easier for planning purposes isn’t good enough for Enterprise-scale projects; these projects need a place where you can find the precise, updated and complete features definition, including all the associated nonfunctional requirements and UI specs.

Differential value of early market features and quick obsolescence of the software products make the software market demand more agile project management methodologies constantly, so methodologies are being adapted and designed to accomplish this goal. In reference to requirements the agile literature and methodologies are oriented to describe how to achieve agile deliveries, decreasing time spent performing exhaustive analyses, design and documentation previous to start implementing and delivering features.

The Agile Manifesto and the related principles say:

  • Manifesto Principle: Our highest priority is to satisfy the customer through early and continuous delivery of valuable software.
  • Manifesto Principle: Welcome changing requirements, even late in development.  Agile processes harness change for the customer’s competitive advantage.
  • Agile related principle: Working software over comprehensive documentation
  • Agile related principle: The most efficient and effective method of conveying information to and within a development team is face-to-face conversation

We can agree about the importance of fast business value delivering through discovery-based requirements and in general using lighter-weight documents and models to initiate the implementation in early stages, but what about the feature specifications integration, management and control? Are we losing the notion of a feature specifications repository? Is this happening because we are scared of committing the sin of not fitting into a standard? Is that job, someone else´s job always?

Being agile doesn’t mean being shortsighted. To be prepared for a later project stage, or for a future project, you have to capture the knowledge that others will convey and rely on. Not everything can be documented, but not everything can exist in the business analysts´ and developers´ minds; therefore preference to document should be given to topics with long-term significance. If a topic has a long-term relevance, then it needs to be documented beyond the limits of the current iteration.

Most agile projects use User Stories as the main placeholder type for requirement specifications and are prone to split the feature´s specification into items, across the iterations. Moreover user stories’ lifespan is bounded to the iterations, and then long-term and consolidated availability of the basic feature specifications becomes an issue.

Reasons for using User Stories this way, among others, are:

  • Stories are used as feature increment units to be placed within the iteration backlogs, using the stories for planning purposes.
  • Stories are prescribed as a good artifact to discuss feature definitions and their scenarios, acceptance criteria and also the developers´ assumptions previous to include them in an iteration backlog.

It is pretentious to tell you what a perfect combination of artifacts is, because you should use what best fits your project, but let me tell you that using just user stories in an enterprise-scale project will get you into trouble soon, and by saying trouble I mean:

  • Having developers continually ask BA, QA engineers continually ask developers and BA already agreed on definitions during every iteration, even on a daily basis.
  • Wasting time implementing feature changes more than once because the team members forget the old acceptance criteria or have contradictory ones without knowing it.
  • QA engineers not testing properly because they forget constraints to test as integrations like nonfunctional requirements.
  • QA engineers not performing all the validations against a feature or not covering all the scenarios. The same thing happens with the test cases accuracy and coverage.

The next graphic shows what I understand as the minimum amount of specs to store and update as long term documentation within a requirement repository.

Being agile doesn’t mean being shortsighted

The requirement repository should allow you to track changes and to version the spec. This can be done with several tools like Wikis, issue trackers, custom issue types, among others.

Having the acceptance criteria of the user stories linked to outer placeholders will make the stories lighter and will avoid content duplicity and you’ll still have the benefits of using stories for planning and discussions purposes.

If somebody wants to read a feature definition, all they need to do, is read everything in one single place.

Following this practice you will still have an agile project; you can adapt agile methodologies to what is most convenient for you. The absence of detailed business rules on a topic within an agile method or framework doesn’t imply exclusion.

Some projects replace the feature spec with automated tests to avoid duplicity and reduce the document´s volume. This is a preference matter but remember that the features´ definitions and constraints should be available to the entire team and reading automated test scripts might be quite difficult, annoying and time consuming.

A well written book about this topic is “Agile software requirements” by Dean Leffingwell. Additionally he and a group of people have created and maintain an interesting framework called “Scaled Agile Framework” oriented to manage Enterprise scale projects.


Related posts

See also


Software development

Software testing

Consultancy & innovation

User experience



Media & entertainment


All industries






Why Belatrix?

International presence

Nearshore advantages

Project governance

Agile expertise

Flexible engagement models

Our talent development