Ask HN: Requirement Doc Training for Business Leaders?

1 points by jerdthenerd 2 years ago | 3 comments

I work on a small development team: approx. 7 devs with some SysAdmin folks with experience in a broad range of tech stacks, languages etc. The Transportation and Logistics industry is notably behind the times when it comes to technology adoption and is still greatly controlled by incumbents and tenured employees. They're used to sending an email to an operator and the person just "does the needful". As we all know, that's not how software works.

I am familiar with the stereotype of folks from Operations/Business not being able to properly define requirements. However, instead of accepting that as reality, I'm trying to do something about it.

So, HN, have any of you been in a company where you've needed to train your Operations teams on requirement documents? Maybe hired an external trainer? How did it go? Any help appreciated.

syndicatedjelly 2 years ago |

Why do they need to write requirements? That’s primarily an engineering function. An engineer should know how to translate the user/business need into a technical requirement.

Let the business and ops people focus on what they’re good at.

jerdthenerd 2 years ago | |

Thanks for your reply. When I describe "the business" I am referring to Product teams that manage SOP, help prioritize new offerings, etc. Here's an example of a feature request from the business:

"I want to allow customers to run scheduled reports from our portal and receive them via email."

Development then designs and executes, delivering a scheduled reporting suite for testing. Business will come back with feedback such as:

"I don't like how I have to select the time for every report. Can't you just default it?" or "Only some users from the customer's account should be able to create/edit scheduled reports. Please add this by Tuesday so I can demo." or even "This is great, but my customer has special holidays that they don't want emails to be sent on. We should have a yearly calendar that prevents reports from getting sent."

There is a large gap between feature request "requirements" and the expectations of the business. Thus, we request specific feature request requirement documents to be turned in prior to development starting work.

syndicatedjelly 2 years ago | | |

It sounds like there's a step missing from that flow - who makes requirements? Saying "I want something" is not a requirement, it's a user need. Not trying to be pedantic, but it might be the lack of definition around what a requirement actually is, that's causing the confusion and rework cycle.

A requirement is typically of the syntax, "{X} system shall {verb} {functionality}". For example, "The brakes subsystem shall convert kinetic energy of the bicycle into heat in the brake pads".

A feature request "requirement" is not a thing. The product team can request features, and someone (an engineer, or a PM typically) needs to create requirement(s) to capture the feature. As part of that process, there should be a back and forth between engineering and the product team to figure out what exactly is desired.