Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question
add comment

10 Answers

up vote 14 down vote accepted

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.

share|improve this answer
    
I've found that you can relatively easily embed data from your tracking system into your wiki, and if you set up some hierarchic bugs you can group them into the requirement, then the project milestones have wiki pages, as do projects, and customers and it all is easy to get your head around. Wiki's re the glue, but still use a bug tracker. Investigate the ability of your bug tracker to point to a web page on the wiki! –  Tim Williscroft Oct 7 '10 at 23:35
    
Absolutely, a wiki is not a replacement for a bug tracking system, it's complementary. Project planning and collaboration is best done on the wiki; issues still need to be tracked on an IMS or priority queue. –  Aaronaught Oct 8 '10 at 0:00
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
1  
I think most of these arguments sound like FUD. Word may not be the best choice, but it isn't that bad: 1. It has quite nice revision/collaboration features for tracking and accepting/rejecting changes, imho way more user friendly than any vcs+diff tools. 2. Styles are more prominent since 2007's ribbon UI. Explaining why styles should be used is probably easier than to explain a whole new software 3. Latest Word can read/save Word 97 files created 16 years ago. Word 2003 can read/save 2010 files using compatibility packs. I agree with 4. and 5. though pdf may be an option for online viewing. –  kapep Dec 29 '12 at 20:09
    
@kapep - my arguments are not FUD in the classical "Fear, Uncertainty and Doubt" sense, perhaps you use "FUD" in some different way. Each of my arguments can be answered. For instance, you could say "Do control-shift-@ on the "Insert" menu to get a line-by-line diff of the current doc against another doc". It can't be done, because all you offered was a counter-opinion. Microsoft has a history of abandoning document formats, or at least making it expensive or difficult to use old formats, which increases upgrade sales, I imagine. –  Bruce Ediger Dec 31 '12 at 0:40
    
Ok I've got to correct me, only 3. seems to be a FUD argument that is often used when it comes to bashing word/doc for being proprietary. Sure microsoft abandoned formats - but doc files have been around very a long time, so 'sooner or later' only applies to archaic versions from last century, if they decide to drop support in >2016 or whenever next word will be released. I also just wanted to point out that there is an easy way to "diff" documents. Of course it isn't comparing line-by-line, that wouldn't make much sense in a non-line-based format. It's more like the inline diff here on SE. –  kapep Dec 31 '12 at 14:15
add comment

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

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!

share|improve this answer
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
1  
There is commercial requirements tracking software available, such as DOORS. –  M. Dudley Jul 13 '11 at 19:44
add comment

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.
share|improve this answer
    
BUT ... once the incomplete requirement is entered, it would be assigned, & whoever it's assigned to needs to resolve any incomplete info wouldn't they? I mean once it's in the system, assuming people are not dropping items, shouldn't it get resolved? I'm not suggesting a complete software layman should enter items, but even if they did .. it's in the system & should be handled. Example: business adds requirement "print receipt" into bug tracker & assigns it to the bus analyst, bus analyst processes it by filling in the holes (via more communication if necessary), then dev gets it. –  John MacIntyre Oct 4 '10 at 21:26
    
Wouldn't any communication breakdown be a symptom of a process problem? (sincerity intended) –  John MacIntyre Oct 4 '10 at 21:27
    
@JohnMacIntyre (1): the result is ping-pong instead of collaboration. The assignee is not always the right person, rare issues can be resolved by only one person; where more people are needed, the assignee rarely has the authority to direct them what to do, rarely sees all dependencies (requirements are rarely independent); lost are the benefits of self-organization, prioritization by ROI or cost of delay, etc. –  azheglov Oct 5 '10 at 1:39
    
@JohnMacIntyre (2): the communication breakdown is of course a sign that their process is not working or that they don't have any process or that they just don't have a healthy communication and collaboration culture in their company. My position is that they should address those root causes. –  azheglov Oct 5 '10 at 1:43
    
@asheglov - I suppose this could be an issue if the assignee is the implementer and isn't allowed to reassign or talk to anybody. But my position is that's not the tool, and that this would happen with the best tools wouldn't it? –  John MacIntyre Oct 5 '10 at 14:30
show 4 more comments

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.

share|improve this answer
add comment

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!

share|improve this answer
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.