How to keep track of all functionality in a large application

Question

As the title says - how to keep track of functionality as the application grows large?

My company use Word-documents where the application has been broken down into chunks called "use cases" - which vary in size and complexity. The problem is that some of them quickly become large and hard to read, as you have to scan between the "happy path" and the edge cases.

We recently started using Visual Studio Team Services for the entire Application Life Cycle - and I wonder if there is a better way than Word-documents - in VSTS or in other systems.

How do you handle this problem in your organization and application? (and if you are using VSTS - do you use any feature of VSTS to tackle the challenge?)

Feeback to answers and comments

• Bart van Ingen Schenau Fun answer. I'd like to relate to the application that way - but there are a lot of applications out there that need to be documented. This is one of them.

• Christophe Thank you for you comprehensive answer. From its contents I realize this is a diverse subject and not one that to be answered easily. From the other comments I also realize that there are many opinions. I appreciate your links and the terms you mentioned. I've already started reading about BPMN and Use Case 2.0.

• Ewan I hoped someone would answer something along your lines. I hoped there would be a standard way of writing automated tests and documentation (at the same time) the same way Test Driven Development (TDD) is done. What I would hope to achive is to immediately see when a change breaks an existing contract, so to speak, of what is supposed to happen.

Feedback to Christophe

The documentation in this app/system contains about 400 use cases. We might have put more or less documentation into each use case than what you would. I suspect more.

I would like to be able to convert most of the documentation into end-to-end-tests. Right now we don't have any end-to-end or UI-tests. We have a lots of unit tests though. Imagine the following:

The x.0 use cases are quite straight forward, but there are quite a few of the x.1 use cases - what we refer to as deviations from the happy path. When counting the 400 uses cases in our product, I didn't include all of the deviations.

I'd like to see a way where the documentation would be the test. Perhaps I could use something like the Gherkin syntax?

Feature: Disallow modifying Product Number when Product is in use
The user cannot modify the Product Number when the Product is in use.

Background:
    Given a product with Product Number 123

Scenario: A user attempts to modify a Product Number when the product is in use
    Given the product being associated with an Order Line
    When I try to change the Product Number to 456
    Then I should see "You cannot change the Product Number, as the Product is already being used"

Scenario: A user attempts to modify a Product Number when the product is not in use
    Given the product not being associated with any other entity
    When I try to change the Product Number to 456
    Then I should see "Changes saved"

Answer 1

Do you need the documentation ?

Large software systems require indeed to keep track of the functionality in a structured fashion:

• I'm not speaking of a system developed by small team where a solid (integration or acceptance) test suite could indeed be sufficient to document what the system does. If needed, developers could always rediscover/reverse engineer a functionality from the test case before discussing evolutions with a new stakeholder.
• I'm rather thinking of larger systems, like an ERP with over 400 use cases and 60 different roles representing thousands of users. Nobody can know or remember all the details. And different stakeholders may have a different understanding of what the system does or shall do.
• In some cases, you may even be obliged to maintain a documentation (SOX regulation for finance, GMP requirement for pharmaceutical production)

There are two main aspects about documenting functionality: what the system does for its stakeholders, and how it is implemented. There is a third: how to keep it up-to-date.

1. What the system does for the stakeholder ?

Problem 1: keep the overview

Suppose a business stakeholder requests some changes in a screen or a flow actions of a UC. Typically, you'd ho through your large flat list of UCs. You'll find the IC. Perhaps you'll identify also some closely related ones that could be impacted as well. But you might miss some less obvious connections and business side effects if you don't realize what's behind their title.

Solution:

• Create a document with the overview of the main business processes in scope (it may be several documents, for large companies organised by domain of activity). Document their decomposition into main steps (typically using some high-level BPMN diagrams).
• Create a correspondence table, where you link the use cases with the process steps.

You can then navigate from the large, and dig down to the right use case, and, conversely, start with any UC and find the business process (and all other potentially related use cases in the same process).

Problem 2: Unreadable complex use cases

The risk, as you explained it, is that UC can grow very complex, either because they are not at the right level of detail, or simply because there are too many variants and exceptions.

Solutions:

• In Writing effective use cases, Alistair Cockburn (one of the author of the Agile Manifesto) explains how to use multilevel use cases, to break down complex UC into several simpler and understandable ones. It's a book with plenty of examples.
• In Use case 2.0 (free ebook), Ivar Jacobson (the inventor of the use case concept and a co-author of UML) proposes a very effective approach, cutting use cases in use case slices. A variant flow would be in a separate slice, so it's much easier to read. The approach has some similarity with Jeff Patton's user story mapping, but with a goal driven approach instead of a feature driven approach.

2. How the functionality is implemented ?

In the domain of technical documentation, there is a heavy risk of over-documenting and writing useless prose that is quickly out of sync and obsolete. You have therefore to be very careful and avoid comprehensive documentation if possible.

The recommendation (an old one from Grady Booch, an OO pioneer and co-autor of UML), is to focus on information that cannot be easily read in the code. So the idea is:

• to explain the main driving principles of the design,
• to give a quick overview on the main components involved
• then focus more on explicing the intent and the main interaction between the components, rather than how a single component works in all its detail (which are already documented BY the code).

Keeping it up-to date ?

If you have a great documentation of a complex living system, after 6 month it'll be outdated. The only way to keep it up-to-date is to take care of this task as integral part of the development process. It should be part of the definition of done.

If you follow the advice for the technical documentation, you'd have to update it in rare cases only (new component, major change in the interactions).

For the UC, it's of course an overhead compared to a simple meeting where things are discussed orally with a key user. But for complex systems, such UC must in general be validated/confirmed by other stakeholders. So in large organisations, this real-time documentation of use case could contribute in making communication more effective.

Answer 2

Automated tests. Ideally with human readable descriptions, maybe BDD style.

These are far superior to documentation as the real danger is adding new features which inadvertently break previous functionality.

With documentation you have to read it all and manually test the application still works as documented.

With the tests you can run all the tests and just see they are green.