Reverse Engineering Requirements: Synthesize, Document, and Validate!

Once you’ve interviewed subject matter experts to understand their business processes and how they use the functionality provided by the system, you’ll most likely be sitting in a state of “information overload.” Trust that this is part of the process of gaining a comprehensive understanding of the system and start working towards creating your end deliverable in small, manageable steps.

This is post 6 of a series on reverse engineering testable requirements by conducting a Current Capabilities Assessment. This is a follow-on post to “Interviewing Subject Matter Experts” where we discussed tips for establishing rapport with your business owners and rooting out requirements.

Document meeting notes

Instead of sitting down and attempting to translate what you’ve just heard into usable documentation, I’d recommend first typing up notes that are more representative of “stream of consciousness” writing.  Read through your hand-written notes and type not just what you managed to get down on paper but everything else these reminders trigger.  Your first goal is to get down on paper “what you heard” and then “what you were thinking”.  I like to use parenthesis or brackets to call out implications of what I heard, for example:

Jane noted that they use they use search to find newly registered customers and verify their credit card transactions went through successfully. [Note to self: why would a credit card transaction not go through? Are we not validating this before registering the customer?]

Writing up notes typically triggers all kinds of questions we simply did not think of while actively engaged in dialog.  This is OK.  It’s simply part of the process.

Ask Follow-Up Questions

If you find big gaping holes, you will want to go back to your subject matter experts and ask some follow-up questions.  If your questions are specific to one feature or you do not expect the answer to have a significant implication, you can ask those questions during validation.  Be sure to capture those questions so you don’t lose them, either in an requirements issues list or within the documentation you are creating.

Start Analyzing and Documenting

Slot everything you’ve learned against your master list and start drafting documents laying out the functionality.  The end goal is to step through each process from beginning to end. Using a structure template can help you analyze the problem space.  I like use cases because laying out the functionality in a sequence of steps, with alternate paths and exception flows helps me think through all the possible scenarios and identify gaps in my thinking.

Once you’ve drafted documentation and before you begin to send it out for review, let it rest for a day or two.  Go back with a fresh perspective as a potential new reader of the documentation.  Is it clear?  Would you be able to gain an understanding of the system? Could you add on to it as the system changes or you learn more?  We often think about the usability of our systems, but rarely about our documentation.  The common thinking is that any documentation is better no documentation.  I disagree. No documentation is better than bad documentation.  For some helpful tips on creating useful and usable documentation, check out Agile Documentation: A Pattern Guide to Producing Lightweight Documents for Software Projects by Andreas Rüping.

Validate the Documentation

Finally, you’ll want to validate your documentation with your subject matter experts.  This activity closes the loop (for them and for you) by presenting back the details of what you understand.  If your subject matter experts are new to this type of documentation, you may want to host a brief tutorial on what the document is and how it will be used.  Always be very upfront about the kind of feedback you expect and very open to comments like “you didn’t get that right.”  In most situations, I’d recommend a brief in-person or over-the-phone walk-through of the document and this is a great time to ask your smaller follow-up questions.  Nothing gets a discussion going like you admitting you did not get all the details in the original discussion.  It makes people more open to provide feedback. On occasion, you and your team will identify some significant holes to be filled. While this is frustrating, sidebar these conversations so you can go back through the whole process, starting with exploratory testing.

We are almost done, but not quite!

So there you are!  I’ve got one more post planned before I officially close out this series — maintaining your documentation — but I’ll continue to post on related topics as I obtain fresh perspectives.  I look forward to continuing the dialog.

Related posts:

1. Reverse Engineering Testable Requirements: Interviewing Business Subject Matter Experts
2. Reverse engineering requirements: Create a Work Plan
3. Reverse engineering requirements: how to explore the system