Question

I have been looking for a collaborative tool for developing functional specifications. I am looking for the ability to:

  • Have multiple users contribute to the specification.
  • Provide some form of traceability, which could be done manually if needed.
  • Provide users with the ability to add comments and notes.
  • Upload and display Visio documents
  • Upload and display mockup screens using Balsamiq Mockup.

My initial impression is that using a wiki could be a good tool for this task. Does anyone have experience with using a wiki for creating functional specifications? What would be the pros and cons to using a tool like this as opposed to a requirements management tool?

Your input is greatly appreciated!

Was it helpful?

Solution

It's possible to do what you describe, to develop requirements in a collaborative way, in spite of using a wiki. Nothing about the wiki paradigm assists in this process.

I managed a wiki on the Zend Framework project to track proposals for components. They're still using it. Proposals are different from functional specifications, but the usage is similar enough to your question that I think this is relevant.

A wiki doesn't take care of itself. Unless you have someone responsible for managing it and making sure there is some structure and consistency, it quickly becomes a mess. The real-world analogy would be to hand each of your team a blank sheet of paper and tell them to write up their part of the requirements. Problems with this are:

  • Every contributor has to make up their own document structure, and write about different things in a different order. So it's impossible to compare one page to another.
  • There's no "index page" to organize all the disparate contributions. No one wants a page to "fall through the cracks," but in a wiki that's the default destiny of any page as soon as it's written.
  • There's no feedback loop to make sure the writing actually gets done.

The way to make it work is to apply some process to the project, and use the wiki in accordance with that process.

  • Give people the ability to create a new page in the wiki, but only through an interface that automatically links the new page into the right index.
  • Define a lifecycle for documents, so they are sure to be drafted, reviewed, and approved at the appropriate stages.
  • Provide a template for a new page. Provide the section headings that you need in each of these pages, and make part of the review process a confirmation that head section has been filled out adequately.

OTHER TIPS

"What would be the pros and cons to using a tool like this as opposed to a requirements management tool?"

While it seems like a great idea, what you run into are people who can't and won't write.

People who can't write -- well -- can't write. They can't communicate with an email or a wiki or any medium outside voice.

  • Some people are "disorganized". Actually, writing is too linear and they don't think linearly.

  • Some people don't get the "write to your audience" and write stuff that's incomprehensible.

  • Sometimes you can't even figure out what they're talking about, much less what they're writing about. They talk in jargon or code. They don't know much but insist on being heard.

Some people won't write.

  • Some people refuse to make commitments. Even in a wiki where it can be retracted. They feel they must pre-discuss everything.

  • Some people are in the habit of doing everything by giving direction to someone else. They either don't write for themselves, or, they make people stand around in their office and listen to them talk and type.

  • Some people are generally toxic on any kind of project. They spring new requirements at the last minute. Their first response is "that will never work". They don't brainstorm well. When they say it work work, and you beg them for an improvement, they don't have one. They just know it won't work.

My experience is that only programmers can use a Wiki successfully. And only senior-level programmers.

  • N00bz don't have enough experience to sort out requirements from design from rumors and management fluff.

  • N00bz don't always have the language skills to write clearly. They may eventually, but one look at their Javadoc comments indicates that they're struggling with the "clarity" part of writing.

It's very appealing. I'm hoping for people to get better at using wiki's because I think it could have a lot of advantages over more traditional approaches where one person interviews everyone and writes things down. But it requires a level of confidence and skill in communication that few people seem to have.

Consider researching Fog Bugz. They tout themselves as the best of the best for project management. Considering Joel's history I'd give them the benefit of the doubt. They use a wiki in the way you've just described.

I would suggest signing up for the free trial, if you're serious. Depending on the size of your project, buying it might be a very good option.

At very least you could look at how they've structured it, or read the forums for ideas on how to build your own stripped down version

Specialist tools help keep things on track and introduce a fixed work-flow. This is kind of the point, keeping things focused and functional. Using generic tools like a Wiki might be great for a bunch of programmers but introducing one for 'mixed-mode' work might be bad:

  1. Things can creep and get off-track quickly
  2. Communication can be lost in the medium

Look at things like Basecamp. They can be thought of as an applied wiki, or collaborative tool. A generic tool for specific purpose needs refining. I don't know if MediaWiki or others have enough customization to keep things clean and focused.

Maybe gather the requirements for your requirements management tool (recursive I know) and what aspects (communication aspects) you can take from the wiki culture and an open-communication mindset. If neither requirements management tools or wikis fit the bill, look at building one. Might be the next big thing. It feels like saying Could I use a wiki instead of Bugzilla?

A fixed work-flow webapp for requirements management with an open-communication emphasis that allows people from many roles to see and understand might be good!

We have used TWiki and now FosWiki in that context. There are many things one gets for free (version control, access control, Web-base access, searches, remote management, security patches, ...). In a few minutes, one can define:

  • a table defining requirements attributes,
  • which creates interactive forms with field selection and validation (where you can also document discussions and rationales, embed images, attach documents, link to other requirements...),
  • and then queries on these "requirements" and show them as tables that can be sorted, filtered, printed, reported against, etc. (e.g., http://jucmnav.softwareengineering.ca/ucm/bin/view/ProjetSEG/JUCMNavRequirementsVer2).

Obviously, one can easily use hyperlinks and Wiki links along the way. FosWiki also has features that can be used to enforce specific workflows, if needed. It is also easy to support forms for use cases and other paradigms (we have done this in the past, and that works generally well).

Wikis such as FosWiki are extensible and one could develop further modules for addressing weaknesses related to traceability management and impact analysis, table-based modifications of requirements, overall packaging, etc.

As a middle ground between a free-form wiki and a requirements management tool, consider using a structured wiki like Foswiki. I haven't done any formal requirements management (with a wiki or otherwise), but I have used TWiki (the predecessor to Foswiki) for other tasks, and it permits you to define a workflow, form fields, and so on as you need them, while keeping the flexibility of a wiki when you don't need a formal structure.

I agree with all (most) of the people above - use of a wiki may sound ok, but wiki's are meant to be present information and be updated as needed, not to be used as an interactive project management tool. I would strongly suggest SmartSheet (I'm a strong advocate of the product) - it provides a spreadsheet like interface where you can store multiple files per row/task, send out automated updates to users and maintain specification revisions... The other approach could be the use of Google email, docs and calendar - a free friendly way of team interaction....I would shy away from issue/bug tracking tools for project management - they tend to have differ on focus: PM tools on the entire project/resource/timeline and Issue tracking tools for specific entered issues....

This may be a bit old now, but I am currently using Atlassian's "Confluence" and it's been great. I currently work as a UX engineer playing the role of "Product Owner" within an Agile process. I can document requirements for discrete interfaces, allow for multiple users' feedback and comments, and intertwine each interface with other interfaces within a larger context (e.g. user story). Everything is very dynamic and template driven. It's suiting my current needs very well.

Licensed under: CC-BY-SA with attribution
Not affiliated with StackOverflow
scroll top