DEV Community


How do you write requirements?

dbanty profile image Dylan Anthony ・2 min read

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)


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


  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.


  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


  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?

Discussion (2)

Editor guide
jwollner5 profile image
John 'BBQ' Wollner

I have worked in all kinds of organizations over the years, and used many different requirements formats, the most structured of which went from strategic product definition (market input, competitor analysis, etc) to formulate meta-epic definitions, through to Jira as a Project and then into actual epic-story-task structures with increasingly refined requirements at each level. It provided amazing tracibility at the sacrifice of time investment up front.

I've also worked in very informal, iterative environments (such as my current employer) where requirements usually start in a meeting or a sales call, then come in through a helpdesk ticket, and refined into a development ticket in VSTS (soon to be Gitlab) and then acted upon, with several rounds of interaction with internal and external customers to refine concept and implementation.

I prefer that internal customers do some level of requirements definition with at least a minimal amount of expectation/requirement, as it gets them thinking about what they really want, and gets them engaged with skin in the game early. That approach needs to be supported by the culture which unfortunately my current environment does not. We may get there over time though as we are going through a sea change in tech leadership right now.

Regardless of tool, I prefer to get everything I can captured in the project wiki, where ever it resides, both for current use and future maintenance.

Keep posting Dylan - This is an old but ongoing issue in every organization and we all need to tip over those stones regularly and get rid of the worms and lizards living underneath!

dbanty profile image
Dylan Anthony Author

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.