Overview

Github does not support include. You can find a rendered version on readthedocs.

Purpose

The doc folder

  • motivates to use light markup text, specifically restructuredText, over DOCX or ODT for documentation of software projects
  • is an example documentation using rstdoc, a wrapper around Sphinx and Pandoc

For your project documenation a readme

  • gives an overview of the documents: Files
  • summaries dependencies between the documents: Dependencies

Files

readme.rest

Overview

readme.rest provides an overview of the documentation, such that new team members or reviewers can find their way in the documentation.

No actual content is placed in the readme.rest file.

ra.rest

Risk Analysis

Motivations and risks.

The argumentation is kept general to motivate general requirements that do not presume solutions.

sr.rest

System Requirements

General requirements motivated from Risk Analysis.

dd.rest

Design Description

The detailed choices made to satisfy System Requirements.

Here the actual format, the conventions and the tools are proposed.

tp.rest

Test Plan

Documentation for the tests of this package (rstdoc).

rstdoc.rest

rstdoc

The description of the python API and command line tools provided by this package.

Dependencies

FCA diagram of dependencies with clickable nodes: ra lightblue, sr red, dd yellow, tp green

tr0:

dhy, r1p, Sustainability, r8d, r90, r9g, Community, Parallelism, Traceability, rj4, Redundancy, Formatting vs Content, rstdcx, Accessibility, Automation, Productivity, s0t, s10, s1g, s45, s8c, scs, seo, sgt, sim, System Requirements, sxr, test_lnkname

Up: tr2, tr4, tr5, tr7, tr8, tr10, tr12, tr13, tr14, tr15, tr16, tr17

Down:

tr1:

Up:

Down: tr3, tr6, tr9, tr11, tr14, tr15, tr16, tr17

tr2:

Accessibility, scs

Up: tr3

Down: tr0

tr3:

Accessibility

Up: tr1

Down: tr2, tr4, tr5

tr4:

Sustainability, r9g, Community, Traceability, rj4, Formatting vs Content, rstdcx, Accessibility, Productivity, s45, sgt

Up: tr3, tr6, tr9

Down: tr0

tr5:

Accessibility, sim

Up: tr3

Down: tr0

tr6:

Traceability

Up: tr1

Down: tr4, tr7, tr8

tr7:

Traceability, s0t

Up: tr6

Down: tr0

tr8:

Traceability, s10

Up: tr6

Down: tr0

tr9:

sgt

Up: tr1

Down: tr4, tr10

tr10:

r1p, Redundancy, sgt

Up: tr9, tr11

Down: tr0

tr11:

Redundancy

Up: tr1

Down: tr10, tr12, tr13

tr12:

r8d, Redundancy, s8c

Up: tr11

Down: tr0

tr13:

Redundancy, s1g

Up: tr11

Down: tr0

tr14:

dhy, Parallelism

Up: tr1

Down: tr0

tr15:

r90, seo

Up: tr1

Down: tr0

tr16:

Automation, sxr

Up: tr1

Down: tr0

tr17:

System Requirements, test_lnkname

Up: tr1

Down: tr0

_images/_traceability_file.png

Figure 1: FCA diagram of dependencies: ra lightblue, sr red, dd yellow, tp green