Welcome to Software Documentation Template!

Todo

Introduce your project and describe what its intended goal and use is.

Relevant Background Information and Pre-Requisits

Todo

Describe what a potential user needs to be familiar with. What should they read and understand beforehand

Describe what a developer needs to be familiar with to further understand the code.

Link to relevant documents or create a new page and add them there.

Requirements Overview

The software requirements define the system from a blackbox/interfaces perspective. They are split into the following sections:

TODO:

Todo

Create a black box view of your software within its intendend environment. Identify all neighboring systems and specify all logical business data that is exchanged with the system under development.

List of all (a-l-l) neighboring systems.

Motivation.

Understanding the information exchange with neighboring systems (i.e. all input flows and all output flows).

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/roboy-sw-documentation-template/checkouts/lite/documentation/ScopeContext/0_system_scope_and_context.rst, line 4.)

Todo

Define what coding guideline they should use, if you differ from the ones below.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/roboy-sw-documentation-template/checkouts/lite/documentation/ScopeContext/1_conventions.rst, line 5.)

Todo

Describe what constraints someone further developing this software should adhere to, and why. Should they not use tool x or operating system y… You can use the table as below, or just put a list.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/roboy-sw-documentation-template/checkouts/lite/documentation/ScopeContext/2_architecture_constraints.rst, line 4.)

Todo

List all technical constraints in this section. This category covers runtime interface requirements and constraints such as:

  • Hard- and software infrastructure

  • Applied technologies - Operating systems - Middleware - Databases - Programming languages

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/roboy-sw-documentation-template/checkouts/lite/documentation/ScopeContext/2_architecture_constraints.rst, line 12.)

Todo

For all your interfaces, define their first 3 levels of interoperability. You can use your doxygen documented source code to i.e. show all members of a class. Find more on the Breathe Documentation

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/roboy-sw-documentation-template/checkouts/lite/documentation/ScopeContext/3_technical_interfaces.rst, line 8.)

Todo

If you have a user interacting with the finished system, and especially if you have a UI or GUI, describe how it can be used. A good way of doing this, is by building a

  • state transition diagram aka the ‘Dynamic UI Behaviuour’ and

  • a mockup/picture of every screen the user can see - aka ‘Static UI’

Don’t overdo it…

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/roboy-sw-documentation-template/checkouts/lite/documentation/ScopeContext/4_user_interface.rst, line 7.)

Todo

If you want to use it, keep track of decisions that someone further developing this software or using it in the future might want to know about. This might save them time or clarify expectations. You can put them as a list, or whatever.

Things to consider:

  • What exactly is the challenge?

  • Why is it relevant for the architecture?

  • What consequences does the decision have?

  • Which constraints do you have to keep in mind?

  • What factors influence the decision?

  • Which assumption have you made?

  • How can you check those assumptions?

  • Which risks are you facing?

  • Which alternative options did you consider?

  • How do you judge each one?

  • Which alternatives are you excluding deliberately?

  • Who (if not you) has decided?

  • How has the decision been justified?

  • When did you decide?

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/roboy-sw-documentation-template/checkouts/lite/documentation/ScopeContext/5_design_decisions.rst, line 6.)

Todo

Describe the installation process step by step.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/roboy-sw-documentation-template/checkouts/lite/documentation/Usage/0_installation.rst, line 4.)

Todo

How do you start the software after installation

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/roboy-sw-documentation-template/checkouts/lite/documentation/Usage/1_getting_started.rst, line 4.)

Todo

Describe your solution strategy.

Contents.

A short summary and explanation of the fundamental solution ideas and strategies.

Motivation.

An architecture is often based upon some key solution ideas or strategies. These ideas should be familiar to everyone involved into the architecture.

Form.

Diagrams and / or text, as appropriate. Keep it short, i.e. 1 or 2 pages at most!

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/roboy-sw-documentation-template/checkouts/lite/documentation/development/00_solution_strategy.rst, line 4.)

Todo

If you have any tests describe:

  • Where the tests are kept.

  • How the tests are invoked.

  • What you can/need to test manually.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/roboy-sw-documentation-template/checkouts/lite/documentation/development/05_test_strategy.rst, line 4.)

Todo

Inset a building block view:

  • Static decomposition of the system into building blocks and the relationships thereof.

  • Description of libraries and software used

We specify the system based on the blackbox view from UML System Context by now considering it a whitebox and identifying the next layer of blackboxes inside it. We re-iterate this zoom-in until specific granularity is reached - 2 levels should be enough.

Motivation.

This is the most important view, that must be part of each architecture documentation. In building construction this would be the floor plan.

Tool

  • Create diagrams as below.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/roboy-sw-documentation-template/checkouts/lite/documentation/development/06_building_block_view.rst, line 6.)

Todo

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/roboy-sw-documentation-template/checkouts/lite/documentation/development/06_building_block_view.rst, line 44.)

Todo

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/roboy-sw-documentation-template/checkouts/lite/documentation/development/06_building_block_view.rst, line 55.)

Todo

Add a runtime view of i.e. the startup of your code. This should help people understand how your code operates and where to look if something is not working.

Contents. alternative terms: - Dynamic view - Process view - Workflow view This view describes the behavior and interaction of the system’s building blocks as runtime elements (processes, tasks, activities, threads, …).

Select interesting runtime scenarios such as:

  • How are the most important use cases executed by the architectural building blocks?

  • Which instances of architectural building blocks are created at runtime and how are they started, controlled, and stopped.

  • How do the system’s components co-operate with external and pre-existing components?

  • How is the system started (covering e.g. required start scripts, dependencies on external systems, databases, communications systems, etc.)?

    Note

    The main criterion for the choice of possible scenarios (sequences, workflows) is their architectural relevancy. It is not important to describe a large number of scenarios. You should rather document a representative selection.

Candidates are:

  1. The top 3 – 5 use cases

  2. System startup

  3. The system’s behavior on its most important external interfaces

  4. The system’s behavior in the most important error situations

Motivation.

Especially for object-oriented architectures it is not sufficient to specify the building blocks with their interfaces, but also how instances of building blocks interact during runtime.

Form.

Document the chosen scenarios using UML sequence, activity or communications diagrams. Enumerated lists are sometimes feasible.

Using object diagrams you can depict snapshots of existing runtime objects as well as instantiated relationships. The UML allows to distinguish between active and passive objects.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/roboy-sw-documentation-template/checkouts/lite/documentation/development/07_runtime_view.rst, line 6.)

Todo

Add a deployment diagram. Contents.

This view describes the environment within which the system is executed. It describes the geographic distribution of the system or the structure of the hardware components that execute the software. It documents workstations, processors, network topologies and channels, as well as other elements of the physical system environment.

Motivation.

Software is not much use without hardware. These models should enable the operator to properly install the software.

You can separate this into different levels…

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/roboy-sw-documentation-template/checkouts/lite/documentation/development/08_deployment_view.rst, line 6.)

Todo

List libraries you are using

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/roboy-sw-documentation-template/checkouts/lite/documentation/development/9_Libraries.rst, line 8.)

Todo

Introduce your project and describe what its intended goal and use is.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/roboy-sw-documentation-template/checkouts/lite/documentation/index.rst, line 10.)

Todo

Describe what a potential user needs to be familiar with. What should they read and understand beforehand

Describe what a developer needs to be familiar with to further understand the code.

Link to relevant documents or create a new page and add them there.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/roboy-sw-documentation-template/checkouts/lite/documentation/index.rst, line 19.)

Contents:

Usage and Installation