Revision as of 09:11, 11 August 2010

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

During each phase of the EUDP process document the work. Usually it is not necessary to include intermediate results, but it can be done in order to document special selection cases.

It is important to capture decisions. If two options are available, document the two options and reason about positive and negative sides of the two options. Make a decision and document what caused the specific decision to be made. Any customer or developer that reads the reasoning should be able to accept the reasoning without questioning and work based on the decisions made.

As the figure above indicates all work in EUDP and agile processes are iterative processes. That is, while working forward trying to analyse and understand the matter returning to the earlier processes to correct misunderstandings, ambiguities, add details, etc. is completely normal. If corrections has to be made to earlier documents that has been delivered, note the new state in the current working document - do not correct already delivered documents.

The documentation reflects the state of the process at specific dates and is delivered regularly to the customer. The continuing work may change the results as the developers gains more detailed insight. The documents cannot directly reflect the iterativeness of the work, but are snapshots of the current state of knowledge.

Prepare any document following these guidelines:

• Use a font with serif's for the body text - it eases the reading
• Write with no more than 72 characters per line - it eases the reading
• Use font size 10 to 12 depending on the selected font
• Do not waist time on fancy layout - it does not ease the reading
• Three levels of headers are sufficient
• Use sans serifs fonts in headers
• On each page place a footer or a header that contains:
  • Name - team name and name of team members
  • Date of print
  • Page number / numbers in total
• Hand in documents either with the pages held together
  • with a staple in the upper left corner - preferable
  • in a binder, that do not hinder reading and noting (consider the left handed portion of the populations ability to note on the right side of the binders)

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.

Engineering and EUDP

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.

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

• Revised Development Strategy
• 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 signature for acceptance

PostProject

• Customers general product accept

Process documentation

• <place holder for intelligent stuff to come :-) >

Epilogue

• Summary or conclusion

Note: Items marked with dots are written or drawing artefacts.

Example

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