Beyond the Document Paradigm – Part 1

May 5th, 2015 by Adam Sandman

agile test management requirements management

Have you ever tried to write a letter in a spreadsheet? Ridiculous idea, right? Or perhaps you’ve tried to do the opposite and store discrete, record-oriented information in a word processor? It can be done using tables, but it’s easier with a spreadsheet.

OK, so maybe all this does is to reaffirm the adage, “Use the right tool for the job.” But there are some jobs for which the right tool is not always initially obvious. I’m thinking of test case management and requirements management. Fledgling organizations and projects beginning to manage test cases and requirements for the first time, often start out with word processors which are easy to use by team members and managers alike. In most cases they are also already available, making the decision very cost effective. The result is textual test specifications and requirements specifications.

However, as requirements and test information grows in volume and sophistication, word processors become ill suited to the task leaving organizations to look for an alternative. Some companies choose to switch from a word processor to a spreadsheet, but this is usually a temporary change, until it becomes apparent that a tool built for purpose is a better option.

Figure 1: Record-oriented test cases in Inflectra’s SpiraTeam

During the transition from document-oriented information to record-oriented data, whether to a spreadsheet or a purpose built tool, there are a number of simple challenges which can make the process difficult, or even unsuccessful, leading some to blame the new tool, which is unfair. Let’s look at a few of the most common mistakes.

Overlooking context and background.

Background, context and routine explanation is easy to put into a document; we do it with almost everything we write. But when moving requirements, user stories, test cases, etc., to a record based system, it is too easy to focus on the meat and ignore the fat. Context, reasoning and other general information are not insignificant but are easily overlooked.

Figure 2: Document background text is easily overlooked

To avoid this oversight, devise a strategy from day 1 for all (seemingly) non-essential information. The two best options are:
a) Store this information in separate records using a tag such as an attribute, to distinguish between a ‘Test’ record and a ‘Background’ object, and
b) Store the background information as an attribute of the test/requirement record itself.
The best choice depends on the type of information, for example introductions are better kept in separate records whereas supporting data such as justifications are better in attributes. Otherwise neither solution is particularly better than the other; it is a matter of preference. The important thing is not to leave out the information entirely.

Being hung-up on report formats.

One of the reasons managers like word processors for record keeping is that they can easily produce relatively good looking reports. I have seen managers make this such an important issue that essential data management needs were trumped by the need to make reports look pretty. Individuals are left pulling their hair out trying to make MS-Word act like a database. Managers need to compromise like everyone else and help the team do their job, not make it harder. Also, requirements and test management tools can often produce better looking reports that people might expect, so make sure everyone appreciates what can be achieved before bemoaning the replacement of a word processor.
In part 2: