Documentation

P R E L I M I N A R Y

NOTE: This content is under editing and might not yet reflect the final result.

---

What

The process of writing documentation of the work while using the EUDP method.

How

The dish

A documentation, that reflects the work that has been performed.

Ingredients

• All phases of the EUDP

Process

Why

Documentation is important in all projects. But there are different requirements to how the documentation is written.

In Education

In an education situation, the process - the road the student(s) followed to get to the goal - is as important as the documentation of the product it self are.

In Industry

In the industry the process it self is less important and the focus is on the documentation of the developed. The documentation must be exactly so complete and detailed, that it enables a colleague to inherit the project and continue the work. This requires that documentation both describes the developed parts as well as the choices made during the work.

In Academia

In academic environments the documentation must reflect the way the scientist work: Describe a problem observed, formulate a hypothesis or a problem statement, describe related work, describe the method applied, describe the experiment (collection of data), describe the analysis of the experiments outcome (analysis of the data), and finally draw the conclusions and putting the work into perspective. The academic work may be iterative going through the described phases several times refining the problem statement, adjusting the experiment, etc. until it reflect the observed problem.

EUDP describes an engineering development method. EUDP can be, and are, used in education environments. In EUDP it is only described how the documentation should be when applied at universities. Companies applying EUDP or variants of it has to define their own documentation standard.

Process Documentation

The process documentation documents the work-processes, that brought the developer to the goal rather than the product it self.

It is important for the mentor to be able to see how the mentee applies the development process. In some situations this might be the only way for the mentor to correct the process that the mentee follows during the project assignment.

Product Documentation

The product documentation documents the construction, the developer has created. It must be detailed enough so the project can be handed over to another colleague. It must describe the choices made during development, so a successor don't have to try out the dead ends just to find them impracticable in the current project.

Example

A complete example will be shown here at a later time.

Notes for further editing

Develop a System Overview Diagram - combine HW-blocks and Classes (SysML could be used).

Rich Picture should in the Launch Phase develop into the System Overview Diagram

Don't let things go into this:

Arnold's Laws of Documentation:
	(1) If it should exist, it doesn't.
	(2) If it does exist, it's out of date.
	(3) Only documentation for useless programs transcends the
	    first two laws.

Documentation artefacts:

Prologue

Introduction to the reader

PreProject Phase

PreAnalysis

Rich Picture

Storytelling

Story cards

Preliminary use cases

Stakeholder analysis

System definition

PreConracting

Plan for Launch Phase

Launch Phase

General Analysis

System Overview Diagram (SOD)

Description of main blocks in SOD

Object identification

User scenarios identification

Abstract Class Descriptions

Class Diagram (SysML + UML)

Use Case descriptions

Interface identification

Interface descriptions

Identification of central functions

Description of functions

Identification of dynamics in the system

Communication Diagrams

Sequence diagrams

State machine diagrams

Exact requirements

General Architecture Design

Design criterias

Subsystem Architecture Diagram

Subsystem interface descriptions

Technical Platform

Hardware specification

Mechanical specification

Software specification

Contracting

Development plan

Product acceptance

Realisation

Strategy and planning

Development strategy

General verification plan

General deployment plan

General development plan

For each timebox

Timebox verification specification

Timebox deployment specification

Timebox development plan

Analysis

Refactored block diagram

Refactored class diagram

Detailed use cases

User interface specification

System interface specification

Dimensioning specification

Design

UML/SysML Deployment view(s)

Mechanical specifications and dimensioning

HW module specification per block

UML SW Deployment view

Class specification

Refactored class diagram

Use case scenarios specifications

Sequence diagrams

Implementation

Mechanical drawings with details explained

Electronic diagrams with details explained

Source code with details explained

Description of integration

Verification

Module tests

Integration tests

Acceptance test

Deployment

Customers signatur for acceptance

PostProject

Evaluation

Customers general product accept

Customers general evaluation of the product

Customers evaluation of the project process

The project teams internal evaluation of the development process and process improvements

Process documentation

Epilogue

Summary or conclusion