• 4
name Punditsdkoslkdosdkoskdo

What are proper way to create requirements documents?

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

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.

  • 0
Reply Report

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.
  • 0
Reply Report

I am rather surprised that nobody so far has recommended the use of a wikifor 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.

  • 2
Reply Report