Ask HN: What software do you use to gather requirements?
We have been gathering our requirements and doing our work breakdown structure (WBS) across Google Docs / Sheets and Word / Excel.
In most scenarios, the requirement is not finalized initially. It goes through multiple iterations. To track these changes needs document versioning. Although, there are ways to version both documents and spreadsheets there are either too technical (code version management system) or difficult to use (Google Docs etc.)
The same challenge exists for the WBS. Here, we can probably use Microsoft Project or something similar.
The question to all HNers -
For both requirement gathering and WBS, what I'm looking for -
1. Some organized way to gather information (preferably in some itemized form)
2. Automatic version management and an easy way to see how things have changed
A bonus would be to somehow link between the requirements and WBS.
This can be either a free, open-source, self-hosted or paid option.
Also, it would be useful to know if anybody is using software like Notion, Outline, OneNote for this purpose.
74 comments
[ 2.8 ms ] story [ 150 ms ] threadEasy 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.
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.
https://www.ibm.com/au-en/products/requirements-management
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.
https://sltoo.dev/workflow.html
[0] https://pypi.org/project/sphinxcontrib-needs/
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.
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.
Organise your statements and requirements. Store them in git. Run a simple HTTP server to share with colleagues.
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.
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.
https://productboard.com
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.
- How big is the company? - How did you get non-tech folks onboard with this approach?
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 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.
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.
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.
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.
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…
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...
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.
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
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.)
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 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.
Import and export with Excel allows everyone to participate, see https://sltoo.dev/workflow.html.
Traceability is a beta-feature at the moment.
- 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