Tips for Maintainability of Requirements vs Usability?

[BizAnalyst]

I've been having interesting discussions on presenting requirements and considering maintainability vs usability.

Our system has a lot of data. My inclination is to define the data and its attributes in one place. Then, when the data is used, put in a cross-reference to where it is defined.

For example, a record of our data can be created or updated. There are two ways to update: a single record at a time, or updating data in a table. I don't want to repeat the exact fields for all of these instances.

Others say it is easier to read the document if the info is repeated in each section. I agree it is easier, but don't think the difference is worth the additional maintenance burden.

Do others have tips on this?

[bkuhn]

I would tend to agree with your approach. I see little value in repeating the same block of text over and over within a req document - inevitably you'll miss making a change in one spot.

This is the great thing about requirements tools, though - you can create the requirement once, and have it populate in multiple places when you print.

B

[AlanAJ]

...easier to read the document if the info is repeated in each section. I agree it is easier, but don't think the difference is worth the additional maintenance burden.

Do others have tips on this?

Rather than duplicate the information, I would recommend "including" it where ever it is required. If you are using Microsoft Word, you would copy the original text in the usual way, but instead of pasting the copied text, choose Paste Special and click on the Paste Link radio button. This creates an OLE link to the original text: any changes to the original should be reflected automatically in its copies.

If you cannot link directly to the original text, you can create a "master copy" of the text and link to that. When the original changes, you have to remember to update the "master copy" as well, but paste-linked copies of the "master copy" should update themselves.

You can make all this appear seamless but I would recommend that copies are clearly identified as such and include a reference to the original source.

Most modern software has a similar capability.

[kwiegers]

I'm in favor of not duplicating information, just pointing to it in some way wherever it should reappear. You can do this as AlanAJ suggests with OLE or with bookmarks in Word, or you can use hyperlinks. I don't think hyperlinks are used nearly as much as they could be in requirements docs. I address this "to duplicate or not to duplicate" issue in chapter 14 of my More About Software Requirements book. There's no perfect answer to this thorny issue.

[MGoyal]

I'm in agreement with the majority here. I think it is best not to duplicate information, and instead to link to it. I try to keep my requirements documents as slim as possible. It has a better chance of being read by the stakeholders.