Ask HN: What software do you use to gather requirements?

I'll probably get downvoted for this but:

https://dilbert.com/strip/2006-01-29

> I'll probably get downvoted for this but:

Don't write that.

Try: "This is a joke, but..." or "From what I've seen..." or something similar.

Not everything needs to be serious but some people here are seriously fed up with "I'll probably get downvoted" (and even if I don't reflexively downvote such comments I see where they are coming from :-)

This is the best approach. I too enjoy the occasional witty/funny but well-placed comment, and being open about it being lighthearted helps a lot to avoid downvotes.

ahhahah

This is awesome.

Brilliant! :))

Pre-AI comic

We use a combination of Markdown + PlantUML, CSV, YAML, Structurizr DSL, and Gherkin feature files under Git version control next to the code to structure the requirements and examples. A GitHub Actions continuous integration workflow does validations and compiles reader-friendly documentation with Mkdocs. We are experimenting with consolidating more and more of this into feature files.

We structure the project and its related projects hierarchically along service design packages, similar to the “class-responsibility-collaboration” breakdown in object-oriented design.

All of our stream-aligned team collaborates continuously on this data as part of sprints, including analysts, managers, software and QA engineers. We recently started to collaborate with the enabling Risk & Compliance team on the same data, and started doing compliance audits using the generated, Git hash-versioned reports.

Our other teams use similar combinations of data, mostly centered around Confluence spaces which enable some form of traceability due to bi-directional linking.

This sounds awesome but very tech-heavy. Two questions:

- How big is the company? - How did you get non-tech folks onboard with this approach?

Currently we are with between 50 and 100 in total, the team in this example is with 9.

We are building inherently complex systems with high compliance and security impact. So all colleagues are aware that we need to manage a lot of requirements and design knowledge in the progress. So there is a strong motivation to re-use information, reducing work and room for errors. And it helps to have some people passionate about knowledge management and making Git-based workflows easy to use. For example by linking the Mkdocs-generated pages to the GitHub file editor.

We are 12 (and hiring). All engineers. Each of our client projects only need 2-3 engineers.

We specialize in software only medical devices. Engineers handle the design controls with input from product owners. We even got a product implemented and a 510(k) cleared using RDM and a team of just 3 engineers.

https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfPMN/pmn...

It adds a little bit of overhead but we think it results in a better product in the end because engineers are thinking more about building the right thing as opposed to just building the thing right. It also results in a safer product since engineers are thinking about risk as they design and implement the product. Automated documentation generation also cuts down on manual process that required non-technical folks in the first place.

Sounds like a very interesting setup! Is there a blog post or something similar with more details?

Not yet. What aspect would be interesting for you to read more about?

That's a lot of jargon. Some I understand, some I don't. Seems like it's a good case study for making a graph !

We use a very similar approach at Innolitics when working on medical-device projects for our clients. We've been slowly creating an open source tool to help streamline all of this (https://github.com/innolitics/rdm). We've used this tool to write 510(k)s for three of our clients now and have a couple of more submissions in progress. Each time we go through it we improve the tool a bit.

It handles requirements gathering, documentation generation, regulatory audits, and design documents. We also have been playing around with Structurizr DSL and so far like it quite a bit. We also have a backend that integrates with GitHub and plan to add backends for GitLab and Jira soon.

JIRA had R4J plug-in that is pretty good if using jira doesn’t upset you. I’ve used it and it works nicely. You get traceability “for free”. There’s additional plugins to enable testing so you can do full requirement to test in JIRA (along with work breakdown if you like that sort of thing). I like JIRA for this because you can put all the conversation about each one in the comments. Gives extra color to the reasoning.

JAMA is a great tool I demoed but couldn’t get the org to buy.

Doors is crap.

I recommend word/ excel if you have <60 requirements. If you have more than a tool like above helps, esp if you need to have traceability to testing.

I've used JAMA at 2 companies so far. It's a bit of a mixed bag. There are parts of it that are great, and parts that are an absolute nightmare.

In a lot of ways JAMA is like Jira - your experience is hugely shaped by how well it's been set up for you at the start.

Have you tried our plugin, Requirement Yogi (on the Confluence side), and if you have, can you share how you would position it on the market, especially compared to R4J for example?

What were the major pain points for you guys? I have a med device startup, and JAMA's automatic document import, traceability matrix, document versioning, and general scriptability put it FAR ahead of similar offerings like Greenlight Guru. We don't have it deployed though due to cost, so I'm curious to know the major problems people have with it.

Hey, I’ve done dozens of similar implementations within Med device companies. Happy to chat -> chris@medlaunchnow.com

We are using Notion and are a small business. Feel very comfortable with UI, Templates, Media Types and collaboration functionality.

We have developed almost 40 "templates" to do almost everything we need from Time Tracking, Mental Health, Job Posts, Project Docs, Daily Task Mgmt and Music, etc

Do you not have IP concerns about Notion storing your data entirely on their servers?

Good point. We just rely on privacy and security of Notion as we do with Google Drive. Its a concern for sure, but we decided to consider Notion reliable

I'm using Notion for almost everything (Wiki-style knowledge base, task/requirement management, note taking, gannt-style timeline).

The killer-feature for me is the clean design. If I look at your Excel sheet, it could take me a minute to start understanding what the doc is about. Notion makes so much easier on the eyes and easy to ingest.

My two previous employers have used Rational DOORS and one of them additionally used MagicDraw.

I would advise that you avoid Rational DOORS at all costs.

DOORS is the kind of abomination that is so bad that I wish a meteorite would smite IBM.

Had to use DOORS for years, now we try Sphinx Needs [0] and like Docs-As-Code in combination with your favorite git workflow very much.

[0] https://pypi.org/project/sphinxcontrib-needs/

Nice to see that sphinx-needs got already mentioned here. As I'm the maintainer of it, let me know if features are missing.

For the rest, if your dev-team is following docs-as-code approach, give sphinx-needs a try. It allows to automate a lot of stuff and integrate external data. So in the end it can save a lot of time.

I'm trying to understand what your workflow is that requires easy-to-use versioning. Aren't you basically always implementing against the current requirements?

I use Google Docs, with difficult-to-use version history if needed unexpectedly. If it's needed expectedly - e.g., because we planned to do something simple, it turned out we needed something more complicated, and we care about documenting for the future why the simple thing doesn't work - then I add a section to the current version of the doc explaining that. Or if implementation started and I need to catch up people who were familiar with the old requirements, then I add a section noting what the changes are.

These docs are generally prose, in the vague space of Amazon-style six-pagers, Architectural Decision Records, RFCs/enhancement proposals (Rust/Python/Kubernetes have great public examples of this), etc.

For extremely complicated requirements, the prose document includes an itemized list of stuff we need to get right, for easy reference, and then a prose explanation of why a particular approach will get them all right.

(In my experience, docs that just have lists are prone to having apparently-contradictory requirements and no explanation of how they're expected to be resolved.)

I use https://cawemo.com/ business process modelling notation (graphical) because it's multiplayer realtime and works well over video.

OneNote for us. I feel like something too formal would add too much bureaucracy to requirements which are often a creative exercise in communication. For example sometimes you need a diagram, a face to face chat, a story etc. to get the ideas across. Getting ideas and concepts across > getting every requirement set in stone for us.

I agree with the creative exercise component. Do you have a check list to make sure everything is collected? How well does this scale up?

By the time a JIRA ticket is created that ticket should have a bullet point list of what is required. But it doesn't really go into minute detail, so we rely on programmers to ask questions, QA / demos etc. to catch that level.

For simple lists, notes, and documentations, (and not spreadsheets), I found gitbook great.

Easy navigation, built-in search, you can have variants (for versioning), less cluttered UI and (anecdotally) good overall performance on mobile and desktop.

Tried asana, dropbox, trello, notion, airtable, and settled with gitbook.

IBM DOORS, but it's probably the worst piece of software I've ever had the misfortune of using.

Lotus Notes woukd like a word with you.

Dear god, back in the day I had to support an entire ticketing system inside lotus notes as a domino app. Never again.

Can DOORS be worse than PTC Integrity?

Maybe that is why their promotional video is people knocking down wooden block towers rather than showing off the UI:

https://www.ibm.com/au-en/products/requirements-management

Excel.

Unless your project is huge (multi billion), requirements gathering is mostly about the BA and others understanding how something will be used. So it's human brain work. Excel is a nice way to keep and monitor lists of requirements and link then together, add dates etc.

It's something everyone can operate (stakeholders to Devs, without a new license or needing to be taught it).

Ive seen a LOT of projects use shiney clever solutions and they always either fall back to people's brains or fall on their face because someone didn't complete the dependency matrix overview page in exactly the way the software needed etc.

Second this - excel seems to work well unless you have a large number of requirements or you need to do multi-level tracing. Scripts can help with the later.

Is this the script you're looking for?

https://sltoo.dev/workflow.html

My organisation uses Aha (https://www.aha.io/) for all of our products. Personally I like it and I believe it meets both of your requirements.

Regarding 1): it has a structured framework where you define your product vision, then break it down into goals and initiatives, then break the initiatives into features. The dev team further breaks down the work into TFS tickets, and Aha integrates with TFS.

Regarding 2) It does change tracking on everything, so you can view the prior history of any ticket in the system.

It is really cool to see our product mentioned on HN (I am a co-founder of Aha!).

With regards to the OPs question, tracking work all the way from the idea request from a customer through to the work that a developer does to implement that idea is exactly what Aha! does best. And this is what we have been working on most recently with functionality specifically for developers: https://www.aha.io/develop.

We are the authors of Requirement Yogi. It is an extension of Atlassian Confluence (Server/Data Center), the famous intranet for companies, which addresses your versioning question.

- I created it when I received my usual 1000-page spec document in Word, in a waterfall project…

- So the software is excellent at numbering requirements (which addresses your first question about itemization), making links between places in the docs, managing dependencies, and letting people free to format their document on Confluence pages,

- We have excellent feedback from customers, but we are still lacking some enterprise features such as managing a million requirements, or inheritance (customers often have a core product and they derive a custom version for 10 or 50 customers).

What I love is that we’re at the articulation between free text and structured database: Customers want to write free text with images and widgets, and they still want structural queries, such as the completion % of their project, but based on the Jira story associated to each couple of requirements… I love what I’m doing!

https://requirementyogi.com

—Adrien

What a lot of teams in my company do is have a less formal part (more like brainstorming) done with Quip (https://quip.com/) before having the more formal part in Amazon WorkDocs (https://aws.amazon.com/workdocs/... Disclaimer, I work for Amazon). Workdocs is a pretty good tool for versioning, commenting on and sharing Word documents, but it's not great for multiple people working on a document at the same time. Quip is great for multiple people working on a document at the same time, but doesn't really have any versioning mechanism.

For personal stuff, I use emacs org mode in a git repo. Org mode lets you define a hierarchical structure to the topic, hide the hierarchy that's not relevant to the part that you're focused on now, track what things you've done, and when relevant provide supporting information in spreadsheets embedded right there. Worth checking out.

Hi, please check https://www.specprojector.com/en/

It is service (startup) for making functional specifications for IT-products.

Strong workflow:

1. Features map - role 1: feature 1, feature 2 - role 2: feature 3, feature 4 2. User story for each feature: I can, I see... 3. Attaching design from Figma 4. Estimating resources 5. Attaching API: GraphQL, REST 6. Attaching tasks from GitLab, GitHub for tracking spend time 7. Generating tasks description 8. Terms knowledge base 9. Modules 10. Generating invoice & contract

1. Slack

2. Miro

3. Roam Research

Each has advantages and disadvantages used as knowledge systems. Slack is directly accessible for the whole team. You can create #thunderbong-stream, and under a thread link directly to message sources. That's directly readable for others, and you'll encourage discussion if you want.

Miro is better for hierarchical organization. Top-level requirements, (or objectives, outcomes if you will), then smaller pieces below.

We use P2 at Automattic which is pretty decent, and people can leave comments. Links between the posts are listed on them. It’s not perfect, but since it’s searchable, it’s great to find out why something is different by having p2 build up a web of related comments/posts.

It’s always interesting to go back 10 years to understand exactly why a decision was made and even see some of the alternatives.

I've been working on https://sltoo.dev, it stores requirements in text files and tracks them with git.

Import and export with Excel allows everyone to participate, see https://sltoo.dev/workflow.html.

Traceability is a beta-feature at the moment.

Mind Mapping is a no brainer for such situations.

1) I use XMind, which has floating topics. I quickly draft mentioned requirements as a floating topics and then break them down into sub-topics

2) After the requirement is clarified then it's a time for prioritisation and I use priority matrix for that.

3) Then you just unify everything under a central mind map topic and "connect the dots".

Related question… Is your team even preserving requirements, especially once you’ve got a test suite?

Traditionally, Systems Engineering views test as a method to verify requirements. Other verification methods include inspection, analysis, and demonstration. But, as tests become more readable, maybe at some point the tests become the requirements…

That's what's predicated by "Specification By Example" [1] practices.

Gojko elaborates into the tooling and requirements preservation aspects in "Are tools necessary for acceptance testing, or are they just evil?"[2]

[1] https://gojko.net/books/specification-by-example/

[2] https://gojko.net/2010/03/01/are-tools-necessary-for-accepta...

Thank you, I’ll give that book a look.

I read the article. After a good amount of time trying Cucumber, I tend to agree with James Shore that specialized acceptance testing tools don’t add enough value to offset the added complexity. I’ve found it more efficient to simply add logging markup to the unit & integration test framework that goes with the language used to implement the app.

The most tester-friendly approach I’ve found is to use Storybook for GUI acceptance and Postman for API acceptance. Those tools keep the tests close to the code, organize scenarios well, and are usable by true non-developers. Plus, test collections in Storybook/Postman double as valuable documentation. I hope Storybook stays focused on real, run-time web components and doesn’t get caught up in too much test-only code.

I’m currently building something like this, though I don’t currently have anything open for actual consumption yet. I’d be interested to know what you’d expect the system to do.

It’s basically a standalone system, but can connect to confluence to retrieve requirements, and/or Jira to turn requirements into tickets.

It allows you to group requirements into an arbitrary number of levels, and keeps track of any changes to the requirement. Major changes to the contents can be tagged as a new version, which can give you an idea of how many ‘breaking’ changes there are.

If you integrate with Jira, and the original ticket is already completed, then it’ll create a new one for the new version of the requirement.

Ideally it’ll have a planning component at some point (e.g. auto gantt chart), but not yet.

I've seen people using archbee.io for similar use case. Archbee is a lightweight docs tool for developers with various integrations so should check your boxes (full disclosure - I'm an investor there :)

Plain text file + git.

REdmine.org Self hosted for us but there may be hosting providers around.

I use ProductBoard. It's fairly expensive but pretty great. I gather requirements into PB and use the inbuilt editor to flesh them out. When a story is ready I push a button and it ends up in Trello (but you can add your own integrations; there's one for github for example). The integrations aren't perfect but I love it. Used it in my last job and brought it in at my current job.

https://productboard.com

The big problem in the requirements field is the ghastly tooling.

Organise your statements and requirements. Store them in git. Run a simple HTTP server to share with colleagues.

For requirements gathering, if i had full control I’d probably use use cases at a level of formality appropriate to the need in plain text, markdown, or asciidoc for behavioral requirements, some text->diagram solutions (mermaidjs covers a lot, fir instance) for DFDs and ERDs, ans gantt charts, and git for version management of the whole thing.

I’ve mostly used Word for requirements/user stories, you can turn on track changes. I’ve mostly used excel for WBS.

I’ve also seen things like JIRA and Trello used for small projects where you don’t need a formal requirements doc and you’re running it scrum or Kanban.

My experience is mostly in non-technology industries.

I use predefined templates I made in Confluence for requirements and tech specs. Part of the page header in the template has a spot to link to the other docs. I defined a process where the person reviewing the document uses inline comments to keep the history clean.

Maaaany projects use a set of Word documents in a repository.

I have used Workflowy and Trello on a lot of projects, both of which make drag-and-drop prioritizing and bucketing "fun". These days it's usually a quick HackMD shared with the team.

The vast majority of projects and companies that don't have some existing enterprise platform (Jira et al) that I've worked at use Trello. It got non-tech staff into the software process. It was simple to get started and just about scaled in all the cases I saw. 15 minutes to explain Trello etiquette was all the assistance most people needed before they were off. It was a breath of fresh air. Whole companies are being organised around Trello boards. I recommended Trello.

That all ended when the pricing changed. $10 per user per month pricing killed that. SMEs I work for are repelled by that cost now. E.g. ~100 employee business baulked at the $15000 annual bill Trello wanted, and they were very cash rich, company cars etc ahoy. Now there's a bunch of shoddy replacements being pushed around "we'll just use Excel for this one" sigh, MS Boards or whatever it's called sigh, no markdown support.

Dynalist

wiki page

Word.