F.A.Q. Traceability

2. How StrictDoc compares to other tools?

2.1. Doorstop

The StrictDoc project is a close successor of another project called Doorstop.

Doorstop is a requirements management tool that facilitates the storage of textual requirements alongside source code in version control.

The author of Doorstop has published a paper about Doorstop where the rationale behind text-based requirements management is provided.

The first version of StrictDoc had started as a fork of the Doorstop project. However, after a while, the StrictDoc was started from scratch as a separate project. At this point, StrictDoc and Doorstop do not share any code but StrictDoc still shares with Doorstop their common underlying design principles:

  • Both Doorstop and StrictDoc are written using Python. Both are pip packages which are easy-to-install.
  • Both Doorstop and StrictDoc provide a command-line interface.
  • Both Doorstop and StrictDoc use text files for requirements management.
  • Both Doorstop and StrictDoc encourage collocation of code and documentation. When documentation is hosted close to code it has less chances of diverging from the actual implementation or becoming outdated.
  • As the free and open source projects, both Doorstop and StrictDoc seem to struggle to find resources for development of specialized GUI interfaces this is why both tools give a preference to supporting exporting documentation pages to HTML format as the primary export feature.

StrictDoc differs from Doorstop in a number of aspects:

  • Doorstop stores requirements in YAML files, one separate file per requirement (example). The document in Doorstop is assembled from the requirements files into a single logical document during the document generation process. StrictDoc's documentation unit is one document stored in an .sdoc file. Such a document can have multiple requirements grouped by sections.
  • In YAML files, Doorstop stores requirements properties such as normative: true or level: 2.3 for which Doorstop provides validations. Such a design decision, in fact, assumes an existence of implicitly-defined grammar which is encoded "ad-hoc" in the parsing and validation rules of Doorstop. StrictDoc takes a different approach and defines its grammar explicitly using a tool for creating Domain-Specific Languages called textX. TextX support allows StrictDoc to encode a strict type-safe grammar in a single grammar file that StrictDoc uses to parse the documentation files using the parsing capabilities provided by textX out of the box.

The roadmap of StrictDoc contains a work item for supporting the export/import to/from Doorstop format.

2.2. Sphinx

Both Sphinx and StrictDoc are both documentation generators but StrictDoc is at a higher level of abstraction: StrictDoc's specialization is requirements and specifications documents. StrictDoc can generate documentation to a number of formats including HTML format as well as the RST format which is a default input format for Sphinx. A two stage generation is therefore possible: StrictDoc generates RST documentation which then can be generated to HTML, PDF, and other formats using Sphinx.

If you are reading this documentation at https://strictdoc.readthedocs.io/en/latest then you are already looking at the example: this documentation stored in strictdoc_02_faq is converted to RST format by StrictDoc which is further converted to the HTML website by readthedocs which uses Sphinx under the hood. The StrictDoc -> RST -> Sphinx -> PDF example is also generated using readthedocs: StrictDoc.

2.3. Sphinx-Needs

Sphinx-Needs is a text-based requirements management system based on Sphinx. It is implemented as a Sphinx extension which extends the reStructuredText (RST) markup language with an additional syntax for writing requirements documents.

Sphinx-Needs was a great source of inspiration for the second version of StrictDoc which was first implemented as a Sphinx extension and then as a more independent library on top of docutils that Sphinx uses for the underlying RST syntax processing work.

The similarities between Sphinx-Needs and StrictDoc:

  • In contrast to Doorstop, both Sphinx-Needs and StrictDoc do not split a document into many small files, one file per single requirement (see discussion doorstop#401). Both tools follow the "file per document" approach.
  • Sphinx-Needs has a well-developed language based on custom RST directives, such as req::, spec::, needtable::, etc. The RST document is parsed by Sphinx/docutils into RST abstract syntax tree (AST) which allows creating an object graph out for the documents and their requirements from the RST document. StrictDoc uses textX for building an AST from a SDoc document. Essentially, both Sphinx-Needs and StrictDoc work in a similar way but use different markup languages and tooling for the job.

The difference between Sphinx-Needs and StrictDoc:

  • RST tooling provided by Sphinx/docutils is very powerful, yet it can also be rather limiting. The RST syntax and underlying docutils tooling do not allow much flexibility needed for creating a language for defining requirements using a custom and explicit grammar, a feature that became a cornerstone of StrictDoc. This was a major reason why the third generation of StrictDoc started with a migration from docutils to textX which is a dedicated tool for creating custom Domain-Specific Languages. After the migration to textX, StrictDoc is no longer restricted to the limitations of the RST document but it is still possible to generate SDoc files to RST using StrictDoc and then further generate RST to HTML/PDF and other formats using Sphinx.
  • Sphinx-Needs has an impressive list of config options and features that StrictDoc is missing. Examples: Customizing the look of the requirements, Roles, Services and others.

2.4. FRET

FRET is a framework for the elicitation, specification, formalization and understanding of requirements.

  • Users enter system requirements in a specialized natural language.
  • FRET helps understanding and review of semantics by utilizing a variety of forms for each requirement: natural language description, formal mathematical logics, and diagrams.
  • Requirements can be defined in a hierarchical fashion and can be exported in a variety of forms to be used by analysis tools.

FRET has an impressive list of Publications.

FRET's user interface is built with Electron.

The detailed comparison is coming.