Changes between Version 1 and Version 2 of Developer/RequirementsEngineering


Ignore:
Timestamp:
Mar 15, 2019, 2:31:25 PM (7 months ago)
Author:
Mikail Yayla
Comment:

Add doorstop summary

Legend:

Unmodified
Added
Removed
Modified
  • Developer/RequirementsEngineering

    v1 v2  
    4949= Tool Summary
    5050
     51== Doorstop
     52
     53Doorstop https://doorstop.readthedocs.io/en/latest/ is an open source requirements management tool  that stores textual requirements in version control alongside source code. Doorstop is much less complex than ProR or Papyrus. Doorstop documents and files have a simple structure with few items and few directives.
     54
     55Materials:
     56* Example document by the author of doorstop: http://jacebrowning.github.io/doorstop/index.html.
     57* The paper about doorstop with use cases: https://www.researchgate.net/publication/276044183_Doorstop_Text-Based_Requirements_Management_Using_Version_Control
     58* Our example document structure: https://depot.tu-dortmund.de/rfek8.   
     59{{{#!comment
     60Upload the example somewhere else.
     61}}}
     62
     63To evaluate doorstop we created a draft of a possible requirements document structure for the queue creation with rtems_message_queue_create in https://docs.rtems.org/branches/master/c-user/message_manager.html#rtems-message-queue-create. In our example document structure the folder pub stores the HTML files of the documents. The other folders   (header, include, llt, reqs, source) contain the YAML document files which make up the doorstop document structure.
     64
     65Pros:
     66* Easy to use, either using the command line interface or creating and editing the documents manually.
     67* The publish directive allows to automatically generate HTML versions of our document structure.
     68* Traceability is enabled by the file structure with fingerprints. When changes occur in the documents, these fingerprints are changed. The doorstop files reside inside a version controlled folder, so changes can be traced.
     69* Markup is used in the text fields of the document files.
     70
     71Cons:
     72* Inconvenient document names when creating documents files using the command line interface, creating them manually can avoid this problem. The issue is shown here as well: http://jacebrowning.github.io/doorstop/REQ.html.
     73* Document files can only reference one source file in their ref field.
     74
     75(Possibe) Bugs:
     76* For the ref field, in the documentation it says doorstop will first search for the file in the ref field (e.g. 'message.h') in the root and its subdirs, and if no file was found it will search for matches in text files. However, for INCLUDE001 in our example, the file 'rtems.h' is searched first although the file 'message.h' exists. We are trying to find out the issue.
     77* For links between doorstop files: When a file has multiple child files it may not show up in the item traceability table in index.html. Because of this we did not use links between files yet (links are used to detect changes in the parent, as these could have an influence on the children). 
     78* Sometimes the HTML files folder has to be cleaned manually from HTML files which were generated by documents which are already deleted.
     79
     80Ideas and options to extend doorstop:
     81* Visualize the document structure as a graph
     82* Improve GUI, currently it can only be used to view the documents
     83* Adapt doorstop such that it accepts reST in the text fields, then we could use text from the documentation
     84* Doorstop supports custom attributes in the document files, but the new attributes are not part of the published documents. Other tools are needed to process them.
     85
    5186= File Formats
    5287