How do you write requirements?

There are tons of posts and classes and videos and podcasts about soliciting requirements, what makes a good requirement, types of requirements, all that. What I can never seem to find is how to actually put the requirements down in a format that is usable.

Im going to lay out my requirements for a requirements doc in the few formats I’ve seen used. Let me know your favorite way to organize requirements and even provide examples if you can.

The Big List

This is usually what I get when I receive requirements from someone. It’s a large, somewhat hierarchical, list of functional requirements. It will look something like this:

1. Clear descriptions of the requirements

2. Traceability

   2.1. Issue tracker should be able to point back to the requirement

   2.2. Future enhancements should reference the original behavior

   2.3. When regression testing, it should be clear what the expected behavior is for a feature at the current version of the project

3. Priority

4. Easy to parse (for humans)

Pros

1. Each requirement gets a unique ID which makes it easy to refer to

Cons

1. It gets very dense very quickly, making it hard to parse
2. No obvious structure, where should you put the priority?
3. Real life requirements rarely fit into a neatly hierarchical list (should security requirements be mixed in as siblings or their own top level?)

Jira Requirements

This can really be whichever issue tracker you use, the premise will probably be the same. Developers tend to do their work against an issue tracker, so it makes sense for them to have all the info they need in one place.

You can create Epics for large features which contain small specific implementation tasks. Epics can span across versions to keep track of improvements made over time.

Pros

1. Unique IDs
2. Easy to link between issues
3. Each issue contains only the info it needs so it’s easier to focus on what you’re trying to read
4. Usually there are comments and history tracking to help evolving requirements

Cons

1. Hard to get a big picture view (depending on how good reporting is for your issue tracker)
2. You have to convince and train whoever is writing requirements to use the issue tracker

Most of the time we use some combination of these two methods, but there’s always confusion at some point. So what do you do, how do you keep your requirements organized?

Comments

[Dylan Anthony]

Thanks John!

At my current place of work we’re still trying to find a solution that works for us. We don’t have a dedicated project manager or BA yet (been searching for around a year now). This means that us developers are left to our own methods for deciding what we write.

I’m still a very young developer, but I’ve seen us make the same mistakes enough to know we need some structure. I’m hoping to come up with some sort of system that gets us more correct information about what we’re building without being so burdensome that no one does it.

Not an easy task 😅 but a worthwhile goal I think.