Laura, Adriana & Mark,

All good stuff. I totally agree with the distinction of requirements vs software docs and that both have value.

First lets dispense with the Software piece as this is a BA forum, but as a developer at heart it gets to me. I have always maintained that systems and program specifications should be written and signed off before any databases, servers, code, etc. are built. These documents should be retained and maintained for the lifetime of an application and no additional documentation should be required or written after delivery.

Now for the business side. Business models are maintainable, reusable artifacts while requirements tend to be project specific artifacts and therefore of limited reuse. Given that, requirements should be generated, if the process is followed correctly, by a change in the business models. Therefore a repository of models which is under constant maintenance can create solution requirements by analysis of the net change.

Requirements Management as a concept is still needed for change control in large projects, but between projects we need a new concept of Model Management with supporting software products. It needs to be understood that business models transcend projects and a project may affect several subject domains, so there is no direct relationship between the two.

If the models are properly automated, then it should be possible to virtually automate the creation of project requirements via model comparisons. However, this will require a major improvement in the skill sets of many BA’s vis-a-vis business modeling as it still seems that many try to elicit requirements out of thin air.

Hi Adriana,
Yes, my efforts in this arena mirror yours – often creating appropriate documentation after-the-fact rather than during the course of the project. I have always thought of these as a form of “requirements documentation.” I suppose “software documentation” might be more appropriate with one exception – how about if the documentation captures business process as well?

I really like this distinction. There is some requirements documentation that should be maintained for reuse, but the greatest benefit I have seen in maintaining documentation beyond the release is software/solution documentation (and business process documentation). This is where the investment seems to have paid off most.

Shouldn’t we BAs be making a distinction between “requirements documents” and “software documentation”?

To me, the distinction is useful because of the different purposes these documents have:

Requirements document: describes the capabilities that the future system will have, for consumption by the project team (developers, testers, etc.) as they create the desired solution and confirm it’s fit for purpose.

Software documentation: documentation created while the software is being built or afterward to capture the system behavior as it has been implemented and create a memory of the team’s knowledge (including the important goal you mention, provide ready-at-hand answers to questions about business rules, logic, and even, “Why did we do that?”, to support future initiatives).

In practice, I find that requirements specifications do not need to have a lot of information that is critical to capture in software documentation for long-term use. For example, developers and testers won’t necessarily care to understand all the history behind a requirement that says “the system must allow users to enter up to 3 product IDs for each product record” — they just want to know that this is a capability they need to implement and test.

However, when we are talking about documents created for long-term knowledge retention, adding “why did we do that?” could save the company a lot of time and money. Using the same example, without proper documentation, when the system is being replaced or upgraded, someone could have the “great idea” of simplify the system by allowing just one product ID to be entered for each product record, only to learn from complaints from users that indeed, one ID is the standard, but the reason why the old system had the option to store up to 3 was that some third-party products actually have 2-3 different product IDs referencing the same item, and storing all of them was a necessity to allow these items to be searched by any of the 2 or 3 possible IDs.

To me, the work you describe doing for your clients is both difficult and extremely valuable for organizations that missed the opportunity to produce this sort of documentation when it would be the most efficient time to generate it — while the project was underway. However, it shouldn’t be called “requirements document”. Even because what was important for your clients at that point is that you documented not only how the system was supposed to work (its requirements) but also how it actually works (which as we all know doesn’t necessarily match the original specification).

What do you think?

Thanks! That makes sense. Examples are great! So sort of like an “included” use case specified at an enterprise level.