When I first started my consulting business, I intended to focus solely on understanding the capabilities of legacy systems. Unearthing requirements had become a bit of a pet passion of mine and I realized that in every BA role I’d had in years prior, 
I was always trying to find a way to better understand what existed today as a foundation to help us build a more solid and valuable future.
Little did I know this task had a special place in the BABOK – Maintain Requirements for Re-Use. The purpose of this task is:
“To manage knowledge of requirements following their implementation.”
OK, so a lot more goes into understanding the capabilities of legacy systems than reusable requirements, but reusable requirements are the primary output of this initiative.
(This post is one installment in our Journey Through the BABOK with BA Stories series.)
There is significant value in maintaining requirements for re-use. The activity can save future business analysts significant time in rediscovering requirements. It can also help speed up the requirements development process for future initiatives by helping provide ready-at-hand answers to questions about business rules, logic, and even, “Why did we do that?” (provided your requirements are documented with some context).
However, even slightly out-of-date requirements quickly lose their value. If you can’t trust the information you find in the requirements document and need to confirm it, the requirements become merely one more source of information, not the authoritative source of information.
Yet, often we do not have time during or after our projects to update requirements specifications or create “as is” system documentation. And, the requirements for one project tend to supersede those of the last one, meaning that project documentation is not necessarily the best way to capture this information.
I’ve started initiatives to have a central repository, much like Adriana describes in part 2 of her article on knowledge sharing strategies, in a few organizations. In one case, I slowly built a repository of use cases, taking each project assignment as an opportunity to discover system functionality in related areas and add it to the main source of requirements documentation. A couple of years later, I was surprised to learn that someone had picked up this documentation and used it as the starting point for a strategic project, which I felt validated the effort I’d put into the materials! While it was likely that some of the content was out-of-date, the structure I’d created for the requirements (another topic we’ll address from the BABOK perspective) proved useful in understanding the system functionality.
In another organization a BA I worked with, started a collection of wiki pages to capture key requirements and business rules. In another, I delegated this effort primarily to the test team, where their first task in supporting a new organization via our quality assurance process was to build a set of functional areas to regression test that were eventually elaborated into specific regression tests.
>>See What These Requirements Documents Look Like
Would you like a starting point for approaching common business analyst work scenarios? Along with work samples so you can see what a typical requirements document looks like? Check out the Business Analyst Template Toolkit – all of the requirements templates are fully annotated and editable by you, giving you a great starting point for starting your first business analyst project or formalizing your work samples.
Laura, I agree it’s an interesting article, and it made me think:
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?
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.
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?
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 Senthilkumar Kandaswamy,
Can you tell me about Business rules? Is it used for data validation purpose? where do you document it?
Akila,
Business Rules describe the operations, definitions and constraints that apply to an organization. (definition from Wikipedia)
In other words, Business Rules are the ones that clearly defines, who is authorized (or not authorized) to perform a function, when (at what point of time) is a certain action permitted (or not permitted), etc.
Business Rules are generally captured within the Use case (or requirements) document, in a seperation section and are referenced in your scenarios (for the Business rules that are applicable for that scenario).
Some useful links on Business Rules:
Wikipedia on Business Rule – http://en.wikipedia.org/wiki/Business_rule
http://www.agilemodeling.com/artifacts/businessRule.htm
Business Rules vs. Business Requirements
– http://www.brcommunity.com/b290.php
Good article – Covers the important aspect of ensuring that the requirements / use case document is kept updated & accurate (most importantly!!). Implementation of ‘Enterprise Use cases’ could also help in making sure that the newer (or later) use cases / requirements pertaining to an existing functionality is not written afresh, but via a re-use of the existing ‘Enterprise Use case’ (if it addresses the same requirement). This avoids a lot of ‘re-inventing the wheel’ and also ‘my version of this functionality!!’ as well 🙂
Thanks Senthilkumar, Enterprise use cases is a new concept to me. Could you elaborate a bit on what they are and how they can be used as a reusable repository of requirements?
Hi Laura,
Enterprise Use case is a concept by which you categorize the requirements / use cases pertaining to fundamentals or the building blocks into a ‘Reusable / Organisational asset’ category. Take for example, ‘Update Employee details’ – across an enterprise, updates to an employee record can only be done in a certain way, to a certain number of fields. The fields that can be updated can be driven / limited by Business Rules, per the group (say HR, Payroll, Admin, etc). So, the ‘Update Employee detail’ can be categorized as an enterprise use case, with business rules detailing out on the additional details.
Did I make it clear? Again, I used my way of telling it with an example. Let me know if you need any additional information. I can elaborate on this, if it would be useful.
Thanks! That makes sense. Examples are great! So sort of like an “included” use case specified at an enterprise level.
Hi Laura, really interesting article.
My last role was a greenfield project where we used Use Cases to capture the functionality the application was to deliver.
I developed the idea of a ‘Use Case Library’ because I saw that over time, as the system developed, each new functionality added was often simply an enhacement/extension to an existing Use Case.
Every Use Case was documented in a separate doc, and stored in the “The Library” – essentially just an intranet repository of versioned documents.
This had a number of advantages –
1. Capturing new requirements was very simple – adding steps/business rules/acceptance critiera to an existing Use Case to create an updated ‘version’.
2. Regression/functional testing was simple – you already had the scripts written (they were the latest version of the Use Cases).
3. We didn’t need any online ‘help’ or guides – the Library “was” the online guide.
4. It encouraged collaboration across the team of BAs and made identifying dependancies between different projects/requirements very transparent.
Mike
Hi Mike,
Thanks for sharing your story. This sounds like a great approach. I’ve had a similar experience where new requirements are best captured as updates to existing use cases instead of new ones. In one project, I updated several use cases that the company had maintained for over 5 years, all color-coded by change date. We were starting to run out of readable colors to make updates in!