0

Is there an accepted way of documenting logic when writing requirements?

I'm trying to document some logic in a requirements document. Currently I just put in a snippet of code, but I know this is wrong. It seems there should be (at least one) standard for documenting logic without being language-specific.

A simplified version of the logic I would like recorded would look like this in code:

ACTION1 should take place when:
     VALUE1=A and ( VALUE2=B or VALUE3 > C)

I could do this, but it seems overly wordy:

ACTION1 should take place when:
    VALUE1=1 and VALUE2=B
ACTION1 should take place when:
    VALUE1=1 and VALUE3>C

I think something like this is intuitive, but I just made it up now:

ACTION1 should take place when:
    VALUE1=1, and 
       VALUE2=B, or
       VALUE3>C

PS: I could include a decision table for the logic, but that seems overkill.

Thanks!

3
  • 6
    If you start to almost code to document your requirements, then you're already in the solution space and no longer in the problem space. Either document your requirements in a way that is easy for the humans to grasp, or start to code to benefit from the interaction with the client. But half/half usually tends to have the inconveniences of both.
    – Christophe
    Commented Feb 2, 2021 at 18:39
  • Yes: use a pencil and paper. Read about UML Commented Feb 2, 2021 at 18:54
  • Such logic is often written by project/product managers in plain English so that it can be easily read and updated in the future.
    – Dan Wilson
    Commented Feb 2, 2021 at 19:15

4 Answers 4

6

At first sight, it looks appealing to go this way.

But when looking closely, I see two issues:

  • If you start to almost code to document your requirements, then you're already in the solution space and no longer in the problem space. Either document your requirements in a way that is easy for the humans to grasp, or start to code to benefit from the interaction with the client. But half/half usually tends to have the inconveniences of both.

  • Your logic will impose a data-driven logic. This might distract from thinking about objectives, behaviors or functions, and responsibilities.

Nevertheless, if however your domain is really heavily logic and fact driven, you may thing of a rule-based engine, where ACTION ...WHEN ... replaces IF .... THEN ... rules. In this case again, your requirements/rules are almost implementation in a domain-specific language.

3
  • "you're already in the solution space" -- this is exactly what I was trying to avlid, and is why I asked. Since in this case the customer does understand straight-up code, and English language would make the actual logic very wordy, I was looking for a middle ground. Thanks! Commented Feb 2, 2021 at 20:33
  • I simultaneously agree with this as an ideal and reject it as practical advice, and I don't know how to reconcile that. You start with an objective like "enter the customer's order into the system", and end up being unable to proceed (or make your own assumptions and end up fixing bugs) until the stakeholders lay down the logic-based rules in detail, like "put the order on hold if the customer's terms code is X, unless they're in group Y." Commented Feb 4, 2021 at 2:09
  • @KevinKrumwiede interesting argument. There is a difference between “put order on hold if the customer terms are FCA(free carrier) unless the customer is in group SMB” (especially if the codes used belong to the user’s jargon), and “PUT ORDER ON HOLD should take place when: VBKD-INCO1=‘FCA’ and KDGRP=‘K03’”. Which one is the clearest for the user to understand and the tester to test? I’d continue to believe in the first one (which is yours) and not the second (OP’s proposal) ;-)
    – Christophe
    Commented Feb 4, 2021 at 8:22
5

Know your audience!

For whom and for what purpose do you write the requirements down?

  • For business people in your organization, for discussing the details? Use plain english, informal style.

  • For making a contract with an external organization? Use plain english, more formal style, proofread by sales people, lawyers or whoever is responsible

  • For IT people, business analysts or developers in your team, so they know what they shall design and implement: you can use user stories, use case diagrams, class diagrams (for data models, for example), other forms of commented UML, BPM diagrams, data flow diagrams, technical english, pseudo code, UI mockups, whatever the formentioned people understand.

  • For some interpreter program which can directly take requirements written down in some DSL and generate tests from it? Then a formal language similar to what you scetched in your question makes sense.

Requirements don't live in a vacuum, context is king.

1
  • Much appreciated. I'm fortunate to have very technical minded customers. So I'll 'stick with what works', which seems to be the common response. :-) Commented Feb 2, 2021 at 20:35
1

Use what works to get the idea from your head space into their head space.

Which is admittedly harder than it looks.

Others have already covered the general ideas:

  • Know your Audience
  • Use visual communication devices like graphs, diagrams, etc...
  • Use informal, and semi-formal language like your inhouse Gherkin Dialect.
  • Talk to the people. I don't know why but so many people miss this. Our second largest brain segment is dedicated to speech processing, might as well use it.

Each person will prefer one medium over another, and you may run into a few that need two or more approaches to get the idea in, like: written and spoken, spoken and visual, handwaving and graphs.

But speaking from a developer head space...

It makes the developers life very difficult when the stories/specs/breakdown favours a particular solution.

For example:

At 12pm a Batch process will run to action all the requests received in the past twenty-four hours.

vs.

Each request needs to be processed within 24 hours of being received. Processing does not have to start immediately, but the business will check at 2pm each day to ensure requests are processed within the 24 hour SLA, as it takes a while to process requests manually.

In the first example as a developer you have already chosen how I'm going to solve this problem, a batch process. Tell me did you check the schedule? Did you take into account late runs, and flow on effects to later jobs? If you did great, your thinking like an engineer. Yet you have a team of engineers sitting around letting you do all the work.

In the second example you have highlighted the forces at play here: the desired outcome, the SLA, the nervousness of the business about meeting that SLA. As a developer I can now think through a range of solutions, and pick the one that will handle these forces and the hidden requirements.

Yes there are hidden requirements, there always are: The system must support Operational concerns like reprocessing a request, or blocking a request from processing. And development concerns like being extensible, and being broken down sensibly. Its harder to ensure these concerns are meet when a single solution is favoured before you get down into the nuts and bolts of the system and think through several solutions. Even better, I am doing my job now.

If there are rules you need to express - that is fine, but express them as they are defined, as business rules.

eg:

When the domain object is "On Hold" obtain permission to take "Off Hold".

....
....
....

A Domain Object is "on Hold"
   When there are two or more reservations
   When there is one reservation, but it has no associated booking.

Let the developer translate that down into what properties, and how it is checked. They may even come back and say, this is better:

A Domain Object is "on Hold"
   When it has a status of "Reserved"
0

Visual Models for Software Requirements and the Requirements Modeling Language defined in that text offers a few suggestions. Specifically for modeling complex decision logic, decision tables or decision trees are the most likely candidates, but state tables or state diagrams may be useful. These visual models can supplement any textual requirements in any format, including shall statements or use cases.

Using SysML, UML, BPMN, or even pseudocode may be useful if your audience is familiar with these notations. Still, for other audiences, they may be unfamiliar and make the requirements less clear. It's important to choose something that aids communication between the people with the requirements and the people implementing the requirements.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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