Requirements Deep Traceability

1. High-level requirements

  • 1.1. Software support for writing requirements and specifications documents

    UID
    GOAL-1-TOOL-SUPPORT

    There shall exist free and lightweight yet capable software for writing requirements and specifications documents

    Technical documentation is hard, it can be an extremely laborious process. Software shall support engineers in their work with documentation.

1.2. Data model

UID
SDOC-HIGH-DATA-MODEL

StrictDoc shall be based on a well-defined data model.

StrictDoc is a result of several attempts to find a solution for working with text-based requirements:

  • StrictDoc, first generation: Markdown-based C++ program. Custom requirements metadata in YAML.
  • StrictDoc, second generation: RST/Sphinx-based Python program. Using Sphinx extensions to manage meta information.

The result of these efforts was the realization that a text-based requirements and specifications management tool could be built on top of a domain-specific language (DSL) created specifically for the purpose of writing requirements and specifications documents. Such a language allows an explicit definition of a document data model which is called "grammar".

1.3. Command-line interface

StrictDoc shall provide a command-line interface.

1.6. Platform support

StrictDoc shall work on all major platforms.

1.6.1. macOS support

StrictDoc shall work on macOS systems.

1.6.2. Linux support

StrictDoc shall work on Linux systems.

1.6.3. Windows support

StrictDoc shall work on Windows systems.

  • 6.1. Uniqueness of UID identifiers in a document tree

    UID
    SDOC-VALIDATION-UNIQUE-UID

    StrictDoc shall ensure that each UID used in a document tree is unique.

    This is implemented but the error message shall be made more readable.

  • 6.3. Valid HTML markup

    UID
    SDOC-VALIDATION-VALID-HTML

    StrictDoc's HTML export tests shall validate the generated HTML markup.

    First candidate: Table of contents and its nested <ul>/<li> items.

1.8. Requirements text format

StrictDoc shall allow storage of requirements in a plain-text human readable form.

1.9. Linking requirements

StrictDoc shall support linking requirements to each other.

1.10. Scalability

StrictDoc shall allow working with large documents and document trees containing at least 10000 requirement items.

1.11. Traceability

UID
SDOC-HIGH-REQS-TRACEABILITY

StrictDoc shall support traceability of requirements.

1.12. Visualization

StrictDoc shall provide means for visualization of requirement documents.

1.13. Open source software

StrictDoc shall always be free and open source software.

2. Implementation requirements

2.1. Parallelization

UID
SDOC-IMPL-PARAL

StrictDoc shall enable parallelization of the time-consuming parts of the code.

2.2. Incremental generation

UID
SDOC-IMPL-INCREMENTAL

StrictDoc shall enable incremental generation of the documents.

When exporting documentation tree, StrictDoc shall regenerate only changed documents and files.

3. Data model

    • 1.1. Software support for writing requirements and specifications documents

      UID
      GOAL-1-TOOL-SUPPORT

      There shall exist free and lightweight yet capable software for writing requirements and specifications documents

      Technical documentation is hard, it can be an extremely laborious process. Software shall support engineers in their work with documentation.

  • 1.2. Data model

    UID
    SDOC-HIGH-DATA-MODEL

    StrictDoc shall be based on a well-defined data model.

    StrictDoc is a result of several attempts to find a solution for working with text-based requirements:

    • StrictDoc, first generation: Markdown-based C++ program. Custom requirements metadata in YAML.
    • StrictDoc, second generation: RST/Sphinx-based Python program. Using Sphinx extensions to manage meta information.

    The result of these efforts was the realization that a text-based requirements and specifications management tool could be built on top of a domain-specific language (DSL) created specifically for the purpose of writing requirements and specifications documents. Such a language allows an explicit definition of a document data model which is called "grammar".

  • 4.1. Primary text implementation

    UID
    SDOC-FMT-PRIMARY

    The SDoc format shall support encoding the Strict Doc Data Model in a plain-text human readable form.

3.2. Project

StrictDoc shall support the "Project" concept as a top-level entity that serves for grouping of SDoc documents into a single project documentation tree.

3.2.1. Project title

Project shall have a "Title" property.

Currently, the project title aspect is not part of the SDoc grammar. It is simply specified via the --project-title command-line option. This might change when the project title will be configured as part of the project-level config file (TOML or SDoc-like grammar).

3.5. Requirement item

3.5.1. Statement

Requirement item shall have a statement.

3.5.2. UID identifier

Requirement item may have an UID identifier.

3.5.2.1. UID identifier format

StrictDoc shall not impose any restrictions on the UID field format.

Conventions used for requirement UIDs can be very different. And there seems to be no way to define a single rule.

Some examples:

  • FUN-003
  • cES1008, cTBL6000.1 (NASA cFS)
  • Requirements without a number, e.g. SDOC-HIGH-DATA-MODEL (StrictDoc)
  • SAVOIR.OBC.PM.80 (SAVOIR)

3.5.3. Title

Requirement item may have an title.

3.5.4. References

Requirement item may have one or more references.

3.5.5. Comments

Requirement item may have one or more comments.

3.5.6. Special fields

StrictDoc shall support customization of the default Requirement's grammar with special fields.

Examples:

  • RAIT compliance fields (Review of design, analysis, inspection, testing)
  • Automotive Safety Integrity Level level (ASIL).

3.7. Links

StrictDoc's data model shall support linking document content nodes to each other.

3.7.1. Parent links

StrictDoc's data model shall support linking a requirement to another requirement using PARENT link.

4. SDoc file format

      • 1.1. Software support for writing requirements and specifications documents

        UID
        GOAL-1-TOOL-SUPPORT

        There shall exist free and lightweight yet capable software for writing requirements and specifications documents

        Technical documentation is hard, it can be an extremely laborious process. Software shall support engineers in their work with documentation.

    • 1.2. Data model

      UID
      SDOC-HIGH-DATA-MODEL

      StrictDoc shall be based on a well-defined data model.

      StrictDoc is a result of several attempts to find a solution for working with text-based requirements:

      • StrictDoc, first generation: Markdown-based C++ program. Custom requirements metadata in YAML.
      • StrictDoc, second generation: RST/Sphinx-based Python program. Using Sphinx extensions to manage meta information.

      The result of these efforts was the realization that a text-based requirements and specifications management tool could be built on top of a domain-specific language (DSL) created specifically for the purpose of writing requirements and specifications documents. Such a language allows an explicit definition of a document data model which is called "grammar".

4.1. Primary text implementation

UID
SDOC-FMT-PRIMARY

The SDoc format shall support encoding the Strict Doc Data Model in a plain-text human readable form.

  • 1.2. Data model

    UID
    SDOC-HIGH-DATA-MODEL

    StrictDoc shall be based on a well-defined data model.

    StrictDoc is a result of several attempts to find a solution for working with text-based requirements:

    • StrictDoc, first generation: Markdown-based C++ program. Custom requirements metadata in YAML.
    • StrictDoc, second generation: RST/Sphinx-based Python program. Using Sphinx extensions to manage meta information.

    The result of these efforts was the realization that a text-based requirements and specifications management tool could be built on top of a domain-specific language (DSL) created specifically for the purpose of writing requirements and specifications documents. Such a language allows an explicit definition of a document data model which is called "grammar".

4.2.1. No indentation

The SDoc grammar's building blocks shall not allow any indentation.

Rationale: Adding indentation to any of the fields does not scale well when the documents have deeply nested section structure as well as when the size of the paragraphs becomes sufficiently large. Keeping every keyword like [REQUIREMENT] or [COMMENT] with no indentation ensures that one does not have to think about possible indentation issues.

4.3. Type safety

The SDoc format shall allow type-safe encoding of requirement documents.

5. Export and import capabilities

5.1. General

5.1.1. Generated file names

StrictDoc shall preserve original document file names when generating to all export formats.

5.2. HTML Export

5.2.1. Single document: Normal form

StrictDoc shall export single document pages in a normal document-like form.

5.2.2. Single document: Tabular form

StrictDoc shall export single document pages in a tabular form.

5.2.3. Single document: 1-level traceability

StrictDoc shall export 1-level traceability document.

5.2.4. Single document: Deep traceability

StrictDoc shall export deep traceability document.

5.2.5. Left panel: Table of contents

StrictDoc shall export all HTML pages with Table of Contents.

5.3. PDF Export

5.3.1. Sphinx documentation generator

StrictDoc shall support exporting documents to Sphinx/RST format.

5.4. Excel Export

UID
SDOC-GEN-EXCEL-EXPORT

StrictDoc shall support exporting documents to Excel format.

5.5. ReqIF import/export

StrictDoc shall support the ReqIF format.

6. Validation

6.1. Uniqueness of UID identifiers in a document tree

UID
SDOC-VALIDATION-UNIQUE-UID

StrictDoc shall ensure that each UID used in a document tree is unique.

This is implemented but the error message shall be made more readable.

6.3. Valid HTML markup

UID
SDOC-VALIDATION-VALID-HTML

StrictDoc's HTML export tests shall validate the generated HTML markup.

First candidate: Table of contents and its nested <ul>/<li> items.

7. Traceability and coverage

7.1. Linking with implementation artifacts

StrictDoc shall support linking requirements to files.

7.1.1. Validation: Broken links from requirements to source files

StrictDoc shall warn a user about all requirements whose links reference source files that do not exist.

7.1.2. Validation: Broken links from source files to requirements

StrictDoc shall warn a user about all source files whose links reference requirements that do not exist.

7.2. Requirements coverage

StrictDoc shall generate requirements coverage information.

Requirements coverage screen shows how requirements are linked with source files.

7.3. Source coverage

StrictDoc shall generate source coverage information.

Source coverage screen shows how source files are linked with requirements.

8. Web frontend requirements

8.1. AJAX updates of multiple web forms

StrictDoc's Web GUI shall provide capability to do multipart updates.