Organising requirements

[MartyLake]

Hi,

I am at the requirements elicitation stage, where I have walls of text in free form, that I want to split into sentences, or even more granular propositions, and map later .sdoc to it. However, free form text don’t have all the requirements one after the other at the same level of details, for example, sometimes a requirement is generally described, then later requirements are described as composite of the first one. How to mark that one requirement is composed of other more detailed?

Another problem I encounter: sometimes requirements are multiplying, for example if feature A, B and C should work in platform X, Y, Z: how to make sure that all combination of AX AY AZ BX BY BZ CY CX CZ are represented? What if more dimensions are involved?

Best,

[stanislaw]

Hey @MartyLake, these are great questions, and I am running out of time to catch up with writing a solid answer. I will get back to this thread within a few days.

[MartyLake]

Amazing, thank you very much for considering answering my questions at some point. I am very interested by your answers.
Best,

[stanislaw]

Hi, I don't know if my answer is good enough and if it is too long or it is too short 😄

I am at the requirements elicitation stage, where I have walls of text in free form, that I want to split into sentences, or even more granular propositions, and map later .sdoc to it. However, free form text don’t have all the requirements one after the other at the same level of details, for example, sometimes a requirement is generally described, then later requirements are described as composite of the first one. How to mark that one requirement is composed of other more detailed?

To my knowledge, there is no clear method for writing requirements, it is still like art in 2023 :), especially if your questions are taken broadly, out of a specific industry's context and best practice or a type of software project.

Here are two guidelines that could give you some guidance:

• https://www.tc.faa.gov/its/worldpac/techrpt/ar0832.pdf
• https://www.incose.org/docs/default-source/working-groups/requirements-wg/gtwr/incose_rwg_gtwr_v4_040423_final_drafts.pdf?sfvrsn=5c877fc7_2

To your specific question:

• StrictDoc has a rudimentary support of COMPOSITE_REQUIREMENT which is a requirement that can consist of child requirements. However, this feature is not supported in the web interface. Also, the use of composite requirements is something that you can rarely find supported by other tools.

• In the absence of composite requirements, you can often achieve a lot by partitioning your requirements document proactively into Sections/Chapters. Typically, a to-be-built product is first decomposed into logical Functions that logically group the requirements, and then the discovered functions become the chapters in your specification document. This process is called Functional Decomposition. The functions can also other functions recursively, so you may end up having a specification document that has a chapter, something like 1.2.3.4 Persistent storage, where the first requirement will be more of a general statement that this particular storage functionality is provided, and then the other requirements in that section elaborate on the first statement by contributing more details. I find this pattern quite common: the first requirement is always one that sets the stage for existing scope (current section / current function) and then you keep adding requirements that further specify the current domain. If you find that a level of detail becomes too fine-grained for the first statement, you create a subchapter and keep doing so, until the whole composition feels "just right" (this is where it connects it to art in my view).

• In addition to the previous point, it is very standard to have more than one document that describes the system. This is especially common when a customer and an implementor are not the same entity. In this case, the parent-level customer document has higher-level statements of WHAT a system should do and the child-level supplier document has lower-level statements of HOW a given solution is to be implemented. In larger projects, you could get up to 4 or more levels of these specification where each next level of specification becomes a HOW-answer to the WHAT-problem of the parent specification. This is what is pretty much called "requirements flowdown" and respectively "requirements breakdown" in the industry. The child specification documents become more and more detailed, down to the level when we can actually talk about which hardware pin is used to provide an interrupt or a software function that calculates a square root in a way needed by a project. How does this all apply to your question? Sometimes, in the very beginning of the requirements analysis, all the statements are just one undifferentiated soup where WHAT and HOW are pretty mixed but as you move forward with understanding the logical groups ("functions" from my previous comment), the natural clouds of related functionality start to emerge, and you start to realize "ok, these requirements are pretty chaotic in relation to each other but at least they are all about the Flash memory or a Sorting algorithm". Then, looking inside each cloud, you could realize that maybe there is a very high-level document that could attract the highest level reqs to it (think gravity in action), while the more specific requirements could be kept in a lower-level how-to spec.

Another problem I encounter: sometimes requirements are multiplying, for example if feature A, B and C should work in platform X, Y, Z: how to make sure that all combination of AX AY AZ BX BY BZ CY CX CZ are represented? What if more dimensions are involved?

A general answer is that I am not aware of how to harness this kind of multiplication using a requirements tool alone. StrictDoc doesn't allow handling such a "combinatorial" requirements writing.

Depending on your problem type, sometimes you could work around the multiplication by modelling your requirement as a table with parameters and values and then writing a test case for each row. Sometimes you may find a clever way to partition your requirements problem, such that the multiplication is avoided, but you and your colleagues can still master the complexity.

To make a general statement: I wish if StrictDoc provided capabilities for dealing with the multiplication out of the box. At the moment, I don't have a clear solution that could be implemented.

Here's some real-world example of what exists, if the topic of embedded C language requirements is not too far from you. One example I know of can be found here: https://docs.rtems.org/branches/master/eng/req/howto.html#action-requirements, where the behavior of C functions was specified as a combinatorial set of input parameters and then expected values. There the EARS syntax was followed and each function was decomposed to a set of requirements each following:

    While <pre-condition 0>, while <pre-condition 1>, …, while <pre-condition n>, when <trigger>, the <system name> shall <system response>.

Splitting each precondition into its own field and writing a custom Python toolchain that assembles the precondition resulted in a very robust coverage of all statements needed for the verification of C functions.

I wish I could give you a better answer, but it should give you some start into the Art 😄 One very good heuristic is that the requirements that you write should be clear and useful. It should be practical to read, manage, implement, verify them, etc.

[MartyLake]

Thank you very much, this is exactly the kind of answers I need at that point in time ! I have read it from top to bottom, will sleep through it, read the two manuals that you linked, and then it will be time to digest and try it out!
This answer is top answer for absolute beginners like I am, and I think it deserves a place in the manual before "getting started".