[trustable-software] Doorstop & Mustard initial comparison

[Jim MacArthur]

I've spent most of today digging further into Doorstop, and wrote some 
thoughts down. As usual, I may have misunderstood some things. Please 
correct me.

1) General analysis of Doorstop & Mustard

Doorstop has fewer rules about nodes; you can create any categories for 
items and link any items together as you wish, as opposed to Mustard's 
explicit categories (requirement, architecture component, work item 
etc). Doorstop establishes a hierarchy for categories. The top level 
category will usually be "Software requirements document", and one might 
then add "high-level design" and "tests" as subcategories of that. 
Documents go into (exactly) one of those categories, and can then be 
linked to any other documents in any category. However, Doorstop 
requires and checks that each document links to at least one document in 
its category's parent category.

A document itself is a single YAML file. 'Document' doesn't imply a long 
piece of text; it could be a single line. Each YAML file has only one 
document in it; there is no tree structure expressed in YAML, although 
Doorstop can import and export tree-style YAML documents. I personally 
find this much easier to deal with than the deeply nested files found in 
Mustard documents. You can lay out data in separate files in Mustard 
too, but previous examples haven't. The placement of documents in the 
directory tree has less effect than in Mustard; the hierarchy of 
categories is not linked to the hierarchy of directories.

A good next step would be to try and transfer some of the Mustard 
example documents into Doorstop. Right now I can't think of any reason 
why that wouldn't work, but actually doing the translation could well 
throw up some issues I've not thought of.

Other things Doorstop has:
* Export and import of .xlsx files, which I think some people will 
prefer to edit rather than YAML. Only spreadsheets in the format 
Doorstop exports can be imported; there is nothing clever to try and 
parse arbitrary spreadsheets, and nothing to deal with Word documents 
yet, as DOORS does.
* An experimental desktop front-end in Tk, which is a good start; I 
would rather develop the web front end, but some people like desktop apps.
* It also has a 'review' command, which I'm unsure as to the intent of; 
from experiments, it looks like the 'reviewed' field is updated whenever 
the Doorstop program checks some YAML and finds it to be consistent; it 
doesn't look like it's meant for the normal process of reviewing changes 
before merging.

Things missing:
* The bare bones of a bottle-based web front end exist, but there's no 
navigation at the moment and no way to view different git branches. You 
can publish static HTML files, which do have navigation in place.

2) Markdown blockdiag processing.

I've just corrected a bug in markdown_blockdiag which stopped it working 
with Python 3; there's still a little setup to do, but you should be 
able to publish documents with blockdiag markup in now.

Details are at 
https://gitlab.com/trustable/overview/wikis/pages/Doorstop_configuration.