What is the proper way to create requirements documents?

Question

Right now my supervisor is creating requirements documentation / specs for me using bugtracking software. This seems like a terrible idea to me, all the requirements are on these little tickets and I have to click around on this dumb webform to get at the requirements. What is a sane software solution for requirements / software specs?

To be clear, I am building this large software component with quite a few features and these features are being set forth in this bugtracking software.

Answer 1

I am rather surprised that nobody so far has recommended the use of a wiki for tracking requirements.

I've found it to be an almost perfect system, because:

• It allows people to collaborate on the requirements and makes this aspect highly-visible;
• It enables you to easily keep the requirements up to date as the project progresses;
• You can go in and see the history at any time, in case of a "that's not what we agreed" dispute;
• Most modern wikis have decent formatting capabilities, so it looks almost as good as a Word doc;
• You can hyperlink directly from your requirements into actual documentation;
• You never have to worry about people working off of different/obsolete copies;
• Requirements can start to be treated as an iterative process, just like design/implementation;
• If the requirements start to get really large/complicated, it's easy to split them up across pages/topics.
• Most wikis accept HTML, so if you really need advanced formatting, you can probably use a tool like Windows Live Writer.

Given the choice, I almost always choose the wiki method these days, it's really quite painless compared to the old-fashioned Word documents or trying to cram it all into a bug tracker.

Answer 2

I always use IEEE Std 830-1998 (IEEE Recommended Practice for Software Requirements Specifcations) as the template for my SRS document. See http://standards.ieee.org/reading/ieee/std_public/description/se/830-1998_desc.html

The final SRS document itself is usually a single OpenOffice.org document, but there are usually many constituent parts that go into it, including spreadsheets and diagrams.

I usually put all of these documents together in a repository that I put into a revision control system, like SVN or CVS. All of the other business analysts, designers, developers, testers, project managers and clients have access to this repository, so they can read it and make edits.

Remember, the SRS is a living, evolving document. It will continue to change and grow for some time. Not only is it important for all stakeholders to have access to the SRS, but its also important to have a complete history of the changes, and the ability to rollback these changes as well, if necessary. So a revision control system works great for this purpose. Good luck!

Answer 3

Using the bug-tracker for requirement management has a tendency to hide the lack of collaboration and communication within the company.

Without passing judgment on any particular method:

• if you're going to use waterfall, you need well-structured, accurate, multi-page documents (not one paragraph that many people typically type as a bug description). These documents are also impossible to write and maintain at a decent level of quality if marketing/salespeople (who originate the requirements) don't work well together with the engineering staff.
• if you're going to use one of the agile methods, then one unit of requirements is a user story, represented by a story card. The card itself is not a requirement, only a starting point of the conversation.

A (brief) experience of one of my past employers with using a bug-tracker for requirements was that it gave many people as very easy way to stop communicating completely. People would simply write a wish, dump it in the bug-tracker, and assume it would eventually come true.

Of course they did so without regard to:

• their own qualifications
• their stake in the project
• conflicts with other requirements
• gaps in requirements
• costs
• any technical considerations
• etc.

Answer 4

I believe that "Word" documents are the wrong way to go for requirements, for the following reasons:

1. No way to "diff" two documents to see what has changed.
2. The user interface discourages using a consistent style throughout. Yes, using styles can be done, but most people can't be bothered because of the difficulty.
3. Document format is essentially hidden. Sure, there's a spec for OLE files, which I guess "Word" docs are, but Microsoft has buried everything useful under tons of blather, so nobody really knows. Sooner or later, your shiny, new "Word" won't open the document.
4. Does not play well with other formats. That is, unless you use Windows and IE, you're out of luck if someone organized a project's documents in HTML files with links to "Word" format files. Click the wrong link, and you have to sit through a long download-and-start-Word period, interrupting the flow of thought. Hyperlinks from "Word" docs to others may or may not work.
5. "Word" is basically for writing documents intended to appear on paper. An admirable goal, but one which makes it less than useful for on-line viewing.

I don't have an alternate suggestion that I have experience with, but I've thought about Python's reStructured Text or Markdown as alternatives.

Answer 5

We generally use Word, but in reality how you create them in software is less important than how you collect the data to create them and whether the person gathering the information knows enough to know when a requirement is overly complicated and will be far more expensive than a simpler requirement yet add no real value to anyone (such as when they want ID numbers to always be assigned in order with none ever skipped) or when it will conflict with an existing requirement or other planned feature. Often the actual users are never talked to and there are many surprises when their managers didn't know something that absolutely had to be done and it isn't inthe new version of the software.

We may also use various pdf, Excel or Visio files as well. All of them for the project are collected and edited out of SharePoint, so we can see earlier versions if need be.

Answer 6

I maintain a product backlog (one per project or product) that contains User Stories. They can be stored in bug tracking software like the one you use. I personnaly use Excel for the backlog and Trac for the sprint backlog (you probably use a tool like that tool).

When required only, I create a Word document that describe the User Story with more details and attach it to the user story. But I try to avoid this by splitting the user story into smaller ones.

Small user stories are easier to manage (including estimation)

I like the Word document because it allows me to put links, formats texts, put tables, screenshots and more, and everybody can read it.

Of course, each User Story is explained in details in the estimation session, and sprint planning, and I'm always available for more questions when the developer decide to work on it. Frequent feedbacks using sprint review prevent developers from doing something differently than requested by the product owner.

Answer 7

Personally, in the past I've used Word Documents, but have resolved to find a tool in the future to manage this for me ... especially with the ability to set bugs to requirements, because a lot of the time, the bug is in the requirements, not the deviation between specs & implementation.

It's never even occurred to me to use a bug tracking tool, but it makes total sense.

Out of curiosity, what is it about it that you do not like?

EDIT: one caveat; tell your manager to rebrand the bug tracking software. Otherwise everything in it is assumed to be a bug. I had this political problem at my last client, where I put tasks in the bug tracker. Not good.

Answer 8

I wrote a requirements database 6 or 7 years ago to handle this. Each requirement record has a short description, a "definition" memo, and a "notes" memo (both rich text, with ability to embed screen shots, etc). There are other fields too, for project, deliverable, sequence number (so they can be ordered logically), use-case/feature it's related to, time estimate, a field for the person handling it, if someone has selected it for implementation, etc.

There's also a "Status" - "Entered", for while we're designing the features; "Approved", set once a group of requirements are reviewed and determined to be ready to implement; "Implemented", set by the programmer once they think the requirement is done, and "Validated" once the QA tech agrees with the programmer. (If the QA tech disagrees, he can set it back to "Approved" so the programmer gets it back.) Requirements can also be "Deferred", "Rejected" or "Questioned" (meaning the Change Control Board needs to look at it.)

The trick to doing this well is reasonable granularity. It can sometimes make sense to have one sentence requirements (e.g. "the problem described in issue 12345 is fixed"), but in general, requirements should describe all the important aspects of a whole feature (or a big chunk of one). For example, a typical "new report" feature will have a requirement for a report format (what the output looks like), and a requirement for the options dialog (explaining the fields, validation, etc.) There might even be a third if there's a complex generator crunching the data, rather than just an easy query or something. In addition, we'll create a "Help" requirement for the corresponding help topic.

There are huge advantages of keeping this stuff in database records rather than a big document. Multiple programmers can be working on requirements at the same time. Individual records are locked so only one person can edit at a time, but they can be opened and read while somebody else is editing. The biggest advantage though is that it provides easy to search documentation of both what the requirements were, and notes about how they were implemented. We have over 25,000 requirements in there now, and we can easily find all the requirements with specific words in all the fields, or the definition, or notes, or whatever, in under 10 seconds. (Try that with 6+ years worth of Word documents.)

I can see why people might say it's a bad idea to do requirements in a "bug tracker", but my guess is that's because the tools suck, not because keeping requirements in a searchable database is a bad idea.

Answer 9

I used once http://www.pivotaltracker.com/ but in my current company we're using .doc as core specification source and Lighthouse as combined features wishlist & issue tracking. For me it's hard to make other people in the team start using any other tools when they are so much used to Word.

Answer 10

If you can follow Agile methodology, the following links can guide you through in choosing a good Agile Project Management tool:

• Agile Project Management Tools
• Comparison of different Agile Project Management Tools

And seriously, try the Agile methodology - it preaches simple, elegant, no-nonsense, non-jazzy, common sensical approach in whatever you do, such that every team member understands and appreciates the role and effort of every other member.

Good luck!