Stakeholders Requirements Specification

Introduction

Document Purpose

This Stakeholders Requirements Specification document identifies the parties interested in the sphinxcontrib-traceables extension, describes their needs, combines the diverse needs in an OpsCon, and derives stakeholder requirements.

This document’s purpose is twofold: on the one hand, to ensure the extension meets its stakeholders’ expectations, and on the other hand, to demonstrate how this extension allows requirements management within Sphinx-based documentation.

Document Scope

This document describes the sphinxcontrib-traceables extension. It is limited to stakeholder-level aspects and therefore doesn’t cover technical details.

Document Structure

The following chapters describe the stakeholders and their needs, combine those needs into a single OpsCon, and derive stakeholder requirements.

Stakeholders and Their Needs

Extension users

STKH-USERS -- Extension users

children
OPSCON-GRAPHS, OPSCON-INSTALL, OPSCON-USAGE
category
Stakeholder

This stakeholder represents users of the sphinxcontrib-traceables extension, i.e. people who write Sphinx-based documentation.

This extension adds traceability functionality to Sphinx. Its users can apply such traceability for various different purposes, such as for example:

Requirements management

Capturing requirements in documentation; tracing the relationships between various types of requirements; generating lists, tables, and diagrams of requirements, and filtering those based on flexible properties of the requirements; tracing requirements to test cases; etc.

Process descriptions

Describing processes as networks of linked items, i.e. “Process 1 ↦ Artifact A ↦ Process 2 ↦ Artifact B ↦ …”, and keeping the textual description there of in line with diagrams by automatically generating diagrams, tables, relationships, etc. from the textual description.

The users’ needs are that this extension provides the functionality they want and is easy to use:

  • Desired functionality

    • Define traceable items and their attributes at arbitrary places within Sphinx documentation

    • Define relationships between traceable items

    • Generate lists of traceable items which are flexibly filtered

    • Generate various output formats showing the relationship between traceable items, such as traceability matrices and graphs

  • Ease-of-use

    • Easy installation

    • Intuitive usage

    • Informative error messages

These user needs are captured in the OpsCon and stakeholder requirements below.

Traceable graph

Traceable graph

Extension developers

STKH-DEVS -- Extension developers

children
OPSCON-DEV, OPSCON-RELEASE
category
Stakeholder

This stakeholder represents developers of the sphinxcontrib-traceables extension, i.e. people who create, expand, and maintain it.

The developers’ needs are that this extension is designed well (easy to expand, easy to maintain, fun to work on, etc.), well documented (easy to understand), and well tested (easy to verify changes don’t break it). Those needs are captured in the OpsCon below.

Traceable graph

Traceable graph

Operational Concept

Developer works on the extension

OPSCON-DEV -- Developer works on the extension

children
STRQ-CONTINTEGR, STRQ-DEVDOCS, STRQ-TESTS
parents
STKH-DEVS
category
OpsConScenario

This scenario covers a developer who works on this extension, expanding its functionality, fixing bugs, writes documentation for it, etc.

Further details for this scenario are yet to be written.

Developer releases the extension

OPSCON-RELEASE -- Developer releases the extension

children
STRQ-CONTINTEGR, STRQ-DEVDOCS, STRQ-TESTS
parents
STKH-DEVS
category
OpsConScenario

This scenario covers a developer who creates a formal release of this extension and publishes that so that users can install the new release (see OPSCON-INSTALL).

Further details for this scenario are yet to be written.

User installs the extension

OPSCON-INSTALL -- User installs the extension

children
STRQ-PIPINSTALL, STRQ-USERDOCS
parents
STKH-USERS
category
OpsConScenario

This scenario covers a user who installs this extension. It consists of the following activities:

  1. A STKH-USERS reads sphinxcontrib-traceables user documentation, specifically the installation instructions.

  2. The STKH-USERS uses a standard method to install this extension; standard methods included here:

    • Python’s built-in pip tool, i.e. pip install sphinxcontrib-traceables

Stakeholders involved with this scenario and requirements derived from it

Stakeholders involved with this scenario and requirements derived from it

User writes documentation

OPSCON-USAGE -- User writes documentation with traceables

children
OPSCON-GRAPHS, STRQ-CLEARERRMSG, STRQ-CONFIGRELTYPES, STRQ-DEFINETRCBLS, STRQ-SHOWTRACES, STRQ-SPECGRAPHS, STRQ-USERDOCS
parents
STKH-USERS
category
OpsConScenario

This scenario covers a user who writes Sphinx-based documentation that contains traceables and other functionality provided by this extension. It consists of the following activities:

  1. A STKH-USERS reads sphinxcontrib-traceables user documentation to learn how to use the extension’s functionality.

  2. The STKH-USERS writes input for Sphinx. The sphinxcontrib-traceables extension provides the following functionality:

    • Define traceable items and their attributes at arbitrary places within Sphinx documentation

    • Define relationships between traceable items

    • Generate lists of traceable items which are flexibly filtered

    • Generate various output formats showing the relationship between traceable items, such as traceability matrices and graphs; see OPSCON-GRAPHS for a scenario describing generation of graphs in more detail

  3. The STKH-USERS runs Sphinx and generates output.

  4. If the input contains errors related to traceables, then this extension gives clear error messages helping the user to quickly understand and fix the error.

User generate graphs showing relationships between traceables

OPSCON-GRAPHS -- User generate graphs showing relationships between traceables

children
STRQ-SPECGRAPHS
parents
OPSCON-USAGE, STKH-USERS
category
OpsConScenario

This scenario covers a user wants the output documentation to include generated graphs showing the relationships between traceables.

Example: Show parents and children of a traceable

In this example the goal is to show the parents and the children of a given traceable. The desired output graph shows the traceable’s parent hierarchy to one side, and its children hierarchy to the other side.

The maximum length/depth to which the hierarchies are shown should be configurable. If not specified, the complete hierarchies should be shown.

This example includes both parent and child relationships in the output diagram. However, The relationship types are not “mixed”, e.g. it does not show all children of a traceable on the “parent side” of the diagram and vice versa. This leads to a nontrivial specification of which traceables to include.

Stakeholder Requirements

Requirements for installation and running

STRQ-USERDOCS -- High-quality documentation for users
children REQ-INSTALLINSTR
REQ-USAGEINSTR
parents OPSCON-INSTALL
OPSCON-USAGE
category StakeholderReq

Users require documentation to help them use this extension. That documentation must cover at least the following topics:

Traceable graph

Traceable graph

STRQ-PIPINSTALL -- Easy installation using pip
parents OPSCON-INSTALL
category StakeholderReq

A very common way to install Python packages is to use the pip tool. It must therefore be possible for users to easily install this extension using the pip tool.

Traceable graph

Traceable graph

STRQ-CLEARERRMSG -- Clear error messages
children REQ-ERRORMESSAGES
parents OPSCON-USAGE
category StakeholderReq

If a user makes an error in his usage of this extension, then this extension should give a clear error message that helps the user quickly find and fix the error (see OPSCON-USAGE).

Sphinx automatically reports on general syntax errors in its input files, usually written in reStructuredText format. This extension therefore does not need to handle such errors.

The error messages to be generated by this extension are mainly related to invalid parameters given to its directives and invalid configuration settings.

Traceable graph

Traceable graph

Requirements for functionality when writing docs with this extension

STRQ-DEFINETRCBLS -- Definition of traceables
children REQ-TRACEDIRECTIVE
parents OPSCON-USAGE
category StakeholderReq

A user must be able to define traceables at arbitrary locations within Sphinx source files using standard reStructuredText constructs (see OPSCON-USAGE).

The definition of a traceable must:

  • Give a unique tag to the traceable, so that it can be referenced throughout the rest of the documentation set

  • Optionally give a title to the traceable

  • Optionally define the traceable’s relationships with other traceables

    • A traceable can have zero or more relationships with other traceables

    • Each pair of related traceables can be related by one or more relationship types

  • Optionally arbitrary additional attributes can be defined for the traceable

    • Examples of additional attributes are: the category, version, color, or foo-value of the traceable

    • Such attributes can be used to group, filter, arrange, etc. traceables

Traceable graph

Traceable graph

STRQ-SHOWTRACES -- Generate overviews of traceables, their attributes, and their relationships
children REQ-TRACEGRAPHS
REQ-TRACELISTS
REQ-TRACEMATRICES
parents OPSCON-USAGE
category StakeholderReq

A user must be able to display traceables, their attributes, and their relationships through out the documentation output. (see OPSCON-USAGE).

The following types of output must be supported:

  • Displays of single traceables and their attributes

  • Lists of traceables and their attributes

  • Tables and nested lists showing related traceables

  • Graphs showing the relationships between traceables

Traceable graph

Traceable graph

STRQ-SPECGRAPHS -- Flexibly specify which traceables to include in graphs
children REQ-TRACEGRAPHS
parents OPSCON-GRAPHS
OPSCON-USAGE
category StakeholderReq

A user must be able to specify in a flexible and powerful way which traceables to be included in graph output (see OPSCON-GRAPHS).

The specification must support at least the usage examples given in the OPSCON-GRAPHS scenario.

Traceable graph

Traceable graph

STRQ-CONFIGRELTYPES -- Configurable relationship types between traceables
parents OPSCON-USAGE
category StakeholderReq

It must be possible to configure the types of relationships that are valid for a documentation set (see OPSCON-USAGE).

The valid relationship types can be configured via Sphinx’s standard configuration method, namely in the build configuration file.

Traceable graph

Traceable graph

Requirements for developers working on this extension

STRQ-DEVDOCS -- High-quality documentation for developers
parents OPSCON-DEV
OPSCON-RELEASE
category StakeholderReq

Developers require documentation to help them understand and improve this extension. That documentation must cover at least the following topics:

  • How this extension is internally structured, so that its workings can easily be understood and so that modifications/improvements will be implemented in-line with its design philosophy (see OPSCON-DEV)

  • How to submit modifications/improvements/bug fixes for review and, if accepted, inclusion in the central repository (see OPSCON-DEV)

  • How to create and publish a formal release of this extension (see OPSCON-RELEASE)

Traceable graph

Traceable graph

STRQ-TESTS -- High-quality tests of this extension's functionality
parents OPSCON-DEV
OPSCON-RELEASE
category StakeholderReq
Traceable graph

Traceable graph

STRQ-CONTINTEGR -- Continuous integration setup for this extension
parents OPSCON-DEV
OPSCON-RELEASE
category StakeholderReq