Changes between Version 1 and Version 2 of Developer/RequirementsEngineering

Timestamp:

03/15/19 14:31:25 (5 years ago)

Author:

Mikail Yayla

Comment:

Add doorstop summary

Developer/RequirementsEngineering

@@ -49 +49 @@
 = Tool Summary
 
+== Doorstop
+
+Doorstop 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.
+
+Materials:
+* Example document by the author of doorstop: http://jacebrowning.github.io/doorstop/index.html.
+* The paper about doorstop with use cases: https://www.researchgate.net/publication/276044183_Doorstop_Text-Based_Requirements_Management_Using_Version_Control
+* Our example document structure: https://depot.tu-dortmund.de/rfek8.    
+{{{#!comment
+Upload the example somewhere else.
+}}}
+
+To 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.
+
+Pros:
+* Easy to use, either using the command line interface or creating and editing the documents manually.
+* The publish directive allows to automatically generate HTML versions of our document structure.
+* 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.
+* Markup is used in the text fields of the document files.
+
+Cons:
+* 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.
+* Document files can only reference one source file in their ref field. 
+
+(Possibe) Bugs:
+* 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.
+* 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).  
+* Sometimes the HTML files folder has to be cleaned manually from HTML files which were generated by documents which are already deleted. 
+
+Ideas and options to extend doorstop:
+* Visualize the document structure as a graph 
+* Improve GUI, currently it can only be used to view the documents
+* Adapt doorstop such that it accepts reST in the text fields, then we could use text from the documentation
+* 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.
+
 = File Formats