1

We're building requirements for some data input that has four different variations. There are some common fields across all four variations, and then some additional fields based on form type.

For example, Q1 and Q2 are available in all four types (A,B,C,D), while some questions only apply to one or some of the different forms.

+------+---+---+---+---+
| Type | A | B | C | D |
+------+---+---+---+---+
| Q1   | x | x | x | x |
| Q2   | x | x | x | x |
| Q3   |   |   | x |   |
| Q4   | x |   |   | x |
| Q5   |   |   |   | x |
+------+---+---+---+---+

Additionally, each field has some extra information about if it's required or what acceptable values can be used. This information can differ across form variations, but is largely consistent.

Form A
+-----------+---------+----------+-------------------+
| Questions | Visible | Required | Acceptable values |
+-----------+---------+----------+-------------------+
| Q1        | x       | x        | Text              |
| Q2        | x       | x        | Date              |
| Q3        |         |          |                   |
| Q4        | x       |          | Integer           |
| Q5        |         |          |                   |
+-----------+---------+----------+-------------------+

In total, there are about 30 data elements, 15 of which are common to all forms.

What seems like the most succinct way to document this?

Repeating a lot of redundant data across multiple data definitions feels wrong. But stuffing too much info into a single matrix feels bloated.

  • What documentation tools are you using? For instance, for a similar problem, I used a wiki (Confluence) and had individual page elements for the shared items and simply included them at the right places in the main document. The net effect was DRY while providing comprehensive information to the reader. – Bob Dalgleish Aug 5 '14 at 20:05
  • Documentation Tools: MS Word and in-house templates... – KyleMit Aug 5 '14 at 20:11
  • MS Word still allows you to include files. – Bob Dalgleish Aug 5 '14 at 20:24
  • Why not document it a form of self-descriptive, automated tests? You haven't told who the audience of this documentation is going to be. – dzieciou Nov 29 '15 at 5:32
1

I think the answer is going to depend on the percent of overlap between requirements.

  • For 100% overlap, a grid seems like the best approach
  • For 0% overlap, separate documentation would be preferable.

And anywhere in between will be a judgement call.

Assuming there's a fair amount of overlap, extending the grid with the common / individual requirements seems reasonable.

+------+---+---+---+---+----------+-------------------+
| Type | A | B | C | D | Required | Acceptable values |
+------+---+---+---+---+----------+-------------------+
| Q1   | x | x | x | x | yes      | Text              |
| Q2   | x | x | x | x | yes      | A,B: list of X    |
|      |   |   |   |   |          | C,D: list of Y    |
| Q3   | x |   |   | x | A: yes   | Integer           |
|      |   |   |   |   | B: no    |                   |
| Q4   |   |   |   | x |          | Boolean           |
+------+---+---+---+---+----------+-------------------+
| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.