How to maintain a spec for a large complex project with repetitive patterns?

Question

I need to maintain a meticulous spec that contains a lot of legal requirements.

We have more than 200 products (and rapidly growing, about 5 products a month) which are all very similar but have differences.

Currently, we find ourselves starting the spec with the following words: "product Y is like X but differs with A, B, C, D..", "product Z is like Y but differs with E, F, G.."

Each product will eventually have more than 100 differences (out of thousands of requirements).

Which is a convoluted way for the developers to understand what the final outcome should look like.

We also need to follow about 6 different documents to understand the full spec for a single product, since some of the requirements are better visualized in a table rather than text and we prefer to maintain them in something similar to a spreadsheet.

Could it actually be that the best way to maintain it is the way we do now? And when product X changes to go to Y, Z etc.. and update them accordingly?

Answer 1

I would make a Template Spec for the similarities.

Then each product starts by referencing the relevant Template Specs and then noting the diferences.

This way, when you change something system-wide, you don't have to update hundreds of specs.

E.g.:

• GUI: This product is a variation of A - see the spec for A at ________
• Other Functionality: This product is a variation of B - see the spec for B at ________
• Delta from A are:
  • X - see section 2.1 for details about X
  • Y - see section 2.2 for details about Y
• Delta from B are:
  • Z - see section 2.3 for details about Z

Ty refraining from chaining products; product F is a variation of product G which is a variation of product A.

Once a product is a basis for another product you probabaly want to turn it into a template.

At the very least, have a clear policy how long chain can be - and how many leaves it can have - before it needs to be made in to a Template Spec of its own.

Idea: If you could use Excel to write your specs, you could reference Template Specs in such a way that they appear as text - and then you can chain - and change - at will and all the specs will be updated all the time.