TWiki for Requirements Management
Note: This topic was factored out from discussions in ActionTrackerPluginDev by ThomasWeigert and BenoitFauvel moved Shawn's thread at the 2003's position.
Our program management team turned up with a proposal for a hacked version of the plugin yesterday that they want to use for requirement tracking. The idea is to have requirement definition pages which are linked to multiple test item description pages, and to use a combination of SEARCHes and ACTIONs to track and trigger state changes in the lifecycle. The advantages to them of using TWiki over commercial alternatives such as DOORS are that (1) requirements can be free-form interlinked - there's no "imposed" structure (such as hierarchical decomposition) to get in the way (2) reporting is entirely under their control - if something more than SEARCH can provide is required, a plugin or quick perl script in data can written very quickly to extract it.
- 18 Jul 2002
[...] Having used both DOORS and RTM for requirements management in past lives, I find our current TWiki solution to be superior.
- 19 Jul 2002
Dave, can you tell us a little bit about how this is used? (you show me yours and I'll show you mine....)
- 21 Jul 2002
If I may add my 2c, out team also would be eager to see a solution for requirements management built on the TWiki ideas. I take it that each requirement would end up as a topic, with a master topic including all the requirements topics in order. However, two key feature of tools such as DOORS or RTM that are yet missing are
- To support the creation of traceability matrices between requirements. Clearly we could produce nets of TWiki linkages along the lines shown in, for example, TouchGraph. However, it would also be nice to process these nets into tables.
- To allow import (and export) of formatted MS Word documents to produce such a web. This seems pretty straighforward: Make all the paragraphs with style "Requirement" topics, everything else goes into the master topic including the requirements topics.
- To allow easy linking between topics. Right now we would have to edit each topic and textually link to the target or source topic. Some means of doing such by selection from menus (as in TopicDropdownbox) would be probably needed.
- 21 Jul 2002
Here is a description of how we use it (although it is evolving).
We design ASICs, the products of each of our projects include an ASIC design, a testbench design, and a set of tests.
When a project is started an initial set of topics is put into the corresponding TWiki web. These include
- A default WebHome topic with high-level issues, actions, and a running status of the project. As well as pointers to the project-specific version control areas, pdf versions of source documents, etc.
- A requirements table. This topic consists of a set of searches to create a table of all requirements sorted by their status.
- A risk summary topic. This topic provides a quick glance of any requirements that have some associated, unresolved, risk.
- An ASIC design template.
- A testbench design template.
- A test status page.
- Various other summary and status pages that make heavy use of the spreadsheet plugin and, increasingly, the graph plugin.
I've hacked the topic create page to allow the user to choose one of several templates for the new topic. When the project starts the default template is for a requirement template. Each requirement includes several fields as parts of the topic body (title, description, child requirements (just a list of wiki-words pointing to other requirement topics), testcases, and notes) as well as a TWiki form (with fields - design allocation, requirement risk, implementation risk, production risk, verification method, testbench allocation, and status).
Requirements are captured directly in TWiki. Hierarchy of requirements is captured by using the child requirement field in the generating requirement and using the 'parent' feature of twiki in each of the children.
Once the ASIC initial design is complete and the high-level blocks have been identified they are entered into the requirement form and allocation to design is carried out, similarly for testbench design. Now at design time a search for all requirements allocated to a particular part of the architecture is easily accomplished (and included on the topic describing the design for that block).
Finally test cases are allocated to tests on the requirement topic. Test cases are generated (at this time the default template for a new topic is the test case template) and include a search that lists all requirements with cases allocated to that test. Test topics include fields like name, description, associated files, referring requirements, issues, as well as a form which includes various kinds of status.
We have recently begun to add development time estimates on design blocks and tests to help in generating and maintaining bottom-up schedules.
Among the strengths of twiki are:
- It allows a database paradigm, but is very forgiving when you decide to change the type/number of fields, etc.
- Any kind of additional data can be attached or linked (e.g. a reference to a PDF version of a third-party document).
- The spreadsheet functions allow for constantly updated status pages, and the new charting plugin makes training of managers even simpler.
- We never run out of licenses
A thing that helps us out is that none of these documents are deliverable to third-parties (e.g. I don't have to generate a MIL-STD-2167 compliant requirements document). Although I think that many customers could be convinced to accept an html-ized version of a project directory as a requirements/design/test document set.
- 21 Jul 2002
Requirements management fits nicely into the TWikiMission
, TWiki should be tweaked over time to facilitate this. Also, a RequirementsManagementCookbook
could be created.
Dave, innovASIC makes use of more advanced TWiki features, how about brushing up your TWikiSuccessStoryOfInnovASIC
with some details you described above?
- 22 Jul 2002
It would be nice if this could have some external tool to dump the document in some nicely printable format. My company works on products that go through FDA approval. That means everything has to go through pretty rigid design control and be able to survive and audit. Our quality manager doesn't want to make the "official" requirements documents be on the computer because of obscenely rigid requirements from the FDA to do this.
- 09 Aug 2002
A couple of thoughts:
We have used HTMLDOC to generate snapshots of our process documentation. It produces a nice PDF file with the internal hyperlinks intact. Another option is to dump a TWiki web to a static HTML
dump and call it a particular version. Each of these is essentially the approach used when you generate documents from a requirements database tool like RTM. I don't have any experience with the FDA but I know that this approach is used fairly widely on FAA projects.
Another piece of the problem is configuration management. In this respect TWiki isn't all that different from any other approach. Once you have an approved baseline access to the web is restricted and a change management process is put in place. No real difference between doing it on TWiki vs. Interleaf vs. Word. This does put a cramp on the collaborative aspects of TWiki but something like a NotePlugin
could help with that.
- 09 Aug 2002
Can you elaborate on the configuration management portion a bit? Would you just set ALLOWTOPICCHANGE to the appropriately authorized individual? Or just trust the team's policy and fall back to verifying conformance with RCS
? I guess another option is to do something like with the KnowlegeBase
and promote pages through the various stages of approval.
- 09 Aug 2002
Sorry for the delay. Generally speaking we've relied on team policy and a configuration manager that monitors changes to the web. The problem is that not all items are at the same level of management. E.G. the requirements get locked up before the design and the test descriptions that are stored in the same web, so it is inconvenient to restrict access to the whole web. If a controlled item is modified then the configuration manager expects to find the appropriate change orders/etc. I'm beginning to lean toward control on an item-by-item basis (i.e. each requirement, test description, etc.), this makes life easier when a development is organized into sucessive builds, some kind of form-based access control would help here, or perhaps a master access list. Another alternative is to use multiple webs for the project but it is a little less convenient.
- 15 Aug 2002
FYI, we use an unpublished plugin called "RevRecover" that allow baselines of document sets to be made. It works by using decorated links such as TopicName?rev=1.2
Of course the baseline page is itself baselined so you only need one version number to recover a documentation baseline.
On the main topic of this page, requirements management; a progress update. We have established an initial process for RM using TWiki; we are just working through the process of adding the requirements for our next (december) release. Already a number of additional plugin features have been developed, mainly to support searching.
Requirements are held in a special web. Within that web, each requirement is a topic which is named "ReQ" followed by the requirement number e.g. ReQ2002 (the numbering is very "anti-wiki", I know, but is what was requested). Forms are used to formalise (sic) the structure of requirements. Each requirement has a number of Test Items, also numbered. A single test item may relate to multiple requirements and vice-versa. Each test item may be linked to one or more test descriptions which describe the test to be performed (either manual or captured in automatic test suites).
- 14 Aug 2002
I've always wondered why the TWiki interface to RCS
is limited the way it is. It would be nice to be able to label the RCS
.txt,v) in a web with a meaningful string ("POST_PDR_02_1_1") and then be to 'walk' through that rev within TWiki by making the requested revision apply until you tell it otherwise.
- 15 Aug 2002
Hmmmm.... we use another sort of tool for doing that sort of thing; it's called "Clearcase"
- 16 Aug 2002
Scary how people can think alike quite independently.
I have been thinking about requirements management and TWiki recently myself. I am a user of DOORS for a few years, I introduced it into my current company and it is just beginning to be used seriously to manage our requirements.
Unfortunatly I've decided that I don't like it much (particularly being a Linux user it is rather hard to use, have to run vmware all the time). I think that the user interface is clunky, the web interface is worse and it tends to discourage people from entering and maintaining the requirements. A TWiki based requirements tool would be so much better. I was thinking along the lines of...
- Have a separate "special" Web per requirements document (as above, SNAP!). Requirements are not just a collection of statements, there really is a heirarchy of documents from customer inputs -> feature lists -> functional requirements and non function requirements -> software requirements, verifiable requirements and even test cases. The heirarchy is not necessarily strict and not all documents are produced for all projects.
- Use "special" TWiki words for each requirement such as ReQ0001 (again, SNAP!). Where the prefix ReQ is defined in the WebPreferences page of the Web foreach requirement document. The numeric suffix needs to be controlled somehow. These must be unique numbers and must never be re-used (you never re-number requirements).
- Use a web form (if I can ever work out how to use them to contain the attributes for each requirement (target release, importance, testable, percent done, etc..)
- Write TWiki tools to do traceability both forward and back and also to do coverage (ie: can every feature be traced to the verifiable requirements). (SNAP again!)
- Baselining (SNAP!). You need to be able to make a snapshot of a completed collection of requirements documents that is easily viewable but not updateable. Using RCS labels seems to be a natural approach to doing this.
I have been writing down my own requirements for this at home and was going to make a start on writing an initial version. I would love to see what others have done and got working and have a play with it to see how well it fits with what I would like to achieve.
- 10 Dec 2002
Is there progress in this area yet? I'd very much like to be able to generate traceability matrices, as well as sort lower level tasks based on ranks of higher level requirements. Of course, I'd like to be able to change the links in the matrices, a la RequisitePro
. I'm quite new to Twiki, so any pointers as to where to start if I need to write my own are greatly appreciated.
- 05 Jun 2003
Hi Jerome, from Motorola's perspective considerable progress, but nothing publishable. We have managed the requirements for our last 2 releases using our solution (large
requirements set). We use Web Forms to capture the requirements, and capture test-items per requirement, linking these to testcases. The action tracker plugin is used to capture milestones in the WBS for each requirement, that can be rolled up to track overall progress. We also make heavy use of links to DDTS to integrate and track response to customer reported issues. Overall, we're getting there, but we're not there yet.
- 05 Jun 2003
At innovASIC we have used the approach described above very successfully on a number of projects (a typical project is 6-8 months in duration). Nothing new to report, we've just refined the process. The one thing that has happened is that more and more project data is being kept in TWiki along with the requirements/test data. This includes design artifacts, customer correspondence, status reports, trip reports, issue logs, review packages/minutes, inspection reports, third-party documentation, user's guides, trade studies, etc. We don't use much of anything beyond the ordinary with respect to TWiki (we use several plugins but they are all fairly standard). The effort to start up is in deciding what data needs to be captured and what relationships between elements are important, then apply the features already available in TWiki.
- 05 Jun 2003
I've got a web site that I'm using to put together a project management example. It needs a lot of work, but it's getting started. The life cycle I'm familiar with is a Cleanroom cycle. Anyway, it would be a good test bed to explore this idea and develop an example. Go further
- 19 Nov 2003