doc/tips/ikiwiki_as_a_requirements_management_tool.mdwn

   1 [[!template id=note text="**Table of contents** [[!toc ]]"]]
   2
   3 Introduction
   4 ------------
   5 At work textual requirements and traceability are daily use terms, often used as contracts with clients or among stakeholders, but at the moment the only way we specify requirements is via a word processor, and traceability is managed manually (ouch!) unless we use a commercial UML (Unified Modeling Language) tool that handles office files, an also allows traceability from design, code and test artifacts. But functionality of that tool is less than basic for requirements.
   6
   7 We are considering the use of a specific requirements management tool, but the problem and something that gets me really frustrated is the extremely expensive price of the licenses of the "de facto" commercial tools we should use. One floating license for both tools (requirements management and modeling) can go beyond $20,000. Of course we can purchase cheaper ones, but I'm tired of this licensing nightmare of worrying about how many licenses are being used, praying not to exceed the limit or restarting a dead license server. We pay companies to not trust us. Taking a look at the FLOSS world doesn't seem to add any reasonable alternative.
   8
   9 These are the raw high level features of the tool I'd like to use:
  10
  11  * Requirements edition
  12  * Requirements attributes edition
  13  * Traceability: edition, coverage analysis and navigation
  14  * External traceability: from requirements in one document/module to requirements in other one (eg: software requirements tracing to system requirements). Note: a set of requirements will be called "module" hereafter in this page.
  15  * Requirements identifiers management
  16  * Requirements history and diff/blame
  17  * Team work
  18  * Easy integration with other software lifecycle tools: modeling (eg. BOUML), project management (eg. Trac)
  19  * Support for other formats such as HTML, office...
  20  * Filtering and searching
  21  * Export facilities to create standards compliant documentation.
  22
  23 Initial idea was to develop a simple web solution using XHTML files. These files would be created in a web broser with existing WYSIWIM editors and store all the stuff in Subversion. All requirements would be stored at the same level (no hierarchies among requirements of the same module) and atomically accessible via a simple web browser. No server side programming would be needed to read requirements. Also special XHTML files (let's call it "views") would be necessary to group requirements hierarchically in a requirements document fashion, using xinclude.
  24
  25 When I first played with ikiwiki I was so happy that many of the ideas I worked on were already in use in this marvelous piece of software, specially the decision to use well-known RCS software to manage history instead of reinventing the wheel, opening also one interesting feature: off-line edition. Other similarity was the absence of special processing for read-only navigation.
  26
  27 So, let's now take all the features above and describe how to make them real using ikiwiki and some simple conventions. Some features would need new functionality and improvement, I'd really appreciate additional ideas on how to better get to the point.
  28
  29 Requirements edition
  30 --------------------
  31 Suppose that all requirements would reside under a concrete folder. We will call it "reqs", and under "reqs" we add as folders as requirements modules we want to use for a system called "foo" (eg. "foo_sss" for system requirements, "foo_srs" for software requirements...). Index file for each document shall be a page summarizing the module: number of requirements, basic coverage information... Other similar pages under the "views" folder could be used in order to have different sets of requirements including additional stuff: introduction, document identification, etc... The rest of the files - actually requirements - shall be markdown files. So editing a requirement would be as simple as adding a page to the wiki.
  32
  33 To create the summary and views, just [[ikiwiki/directive/inline]] and [[ikiwiki/directive/pagecount]] directives could provide nice pages. The uncomfortable part is having to use many [[pagespecs|ikiwiki/PageSpec]] to create the whole views, but it actually shoud work. One possible workaround would be an external tool to handle this and create directives automatically or graphically.
  34
  35 Requirements attributes
  36 -----------------------
  37 There are lots of useful data to associate to a requirement. Eg:
  38
  39  * If it is traceable or not
  40  * Its criticality level
  41  * Its priority
  42  * If it is funtional or not
  43
  44 How to implement this? Using [[ikiwiki/directive/meta]] could be a solution, not tried yet, I'd rather keep requirements content alone. Storing this information in SVN it is easy, although ikiwiki does not provide a way to do it it would imply really little effort. The requirement in itself is the content of the file; attributes are stored as key-value pairs in the file's properties. AFAIK this is a feature available only in SVN, although git has something similar (gitattributes) although path based, but anyway whichever RCS is used, a ".properties" file could be created always when a requirement file is created.
  45
  46 Traceability: edition, coverage analysis and navigation
  47 --------------------------------------------------------
  48 This is the most important feature of a requirements engineering tool. How to do this with ikiwiki? There are some ways, from extremely simple ones to more sophisticated:
  49
  50  * One simple solution: Links. Just link from one requirement to another one to create a traceable directional connection
  51  * One harder: file attributes (see section about requirements just above)
  52
  53 For coverage analysis , using [[ikiwiki/directive/pagecount]] is the perfect solution to summarize and show covered and uncovered requirements. We could add several pages per module - probably using template pages-  with ready made coverage analysis reports... Wow!!! [[ikiwiki/directive/linkmap]] directive can show traceability information graphically.
  54
  55 Navigating among requirements needs... Nothing!!! Just follow the links of referring pages that ikiwiki adds by default.
  56
  57 External traceability
  58 ---------------------
  59 Being just different folders under the wiki, external traceability is as easy as internal.
  60
  61 Requirements identifiers management
  62 -----------------------------------
  63 Another useful convention: requirement identifier shall be the name of the requirements file. In ikiwiki page title is the same as requirement Id. No trouble, it works. I personally prefer to keep title as page title and create a short auto-increasing numeric codes with prefixes and/or suffixes as file name (eg. SRS_FOO_0001, SSS_FOO_002), hope to have somethig running soon.
  64
  65 Requirements history and diff/blame
  66 -----------------------------------
  67 Out of the box! And really much more useful than average diffing components of requirement management tools. There are plenty online front ends to use and for offline work tools like meld are awesome.
  68
  69 Team work
  70 ---------
  71 Also no need to do anything, RCS software does it all. Also for experienced users merging and conflict solving can provide much more practical solutions (most requirements management tools work blocking).
  72
  73 Easy integration with other software lifecycle tools
  74 ----------------------------------------------------
  75 Modeling tools: as a general rule, store model elements in the most atomic parts: classes, enums, actors, use cases... and use again file attributes to store traceability information. Other way is transforming files representing these atomic model parts in independent mdwn files under, for example, a "mdl" folder
  76
  77 Trac integration is so simple... As simple as any PM tool that acceses the same RCS as ikiwiki does. Diffing, blaming, even navigating directly to ikiwiki generated pages. Integration of a ticketing system will give awesome power to all the team.
  78
  79 Support for other formats
  80 -------------------------
  81 Out of the box, at least for wiki and mathematical formats, and creating additional ones shouldn't be so difficult.
  82
  83 Filtering and searching
  84 -----------------------
  85 Look that box in the top right corner?
  86
  87 Export facilities
  88 -----------------
  89 Views with custom styles and html conversion tools would be enough for most purposes.
  90
  91 That's all!
  92
  93 One funny thing: our "de facto future" requirements management tool, after years of research included some years ago a really nice feature: a Discussion tag per each requirement... See this in ikiwiki? Again out of the box!!!
  94
  95 Comments are really welcome!!!