Difference between revisions of "Documentation"

Revision as of 11:59, 23 August 2010

What

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

P = Prologue, E = Epilogue

How

The dish

A documentation reflecting 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 decision 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 have to be made to earlier documents that have 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 gain more detailed insight. The documents cannot directly reflect the iterativeness of the work, but are snapshots of the current state of knowledge.

Below is a complete collection of artefacts that an EUDP process can produce. It is usually not all methods from EUDP that match a project. EUDP is a tool box with a number of methods that help the developer analyse, design and implement a new product and the developer must at any time evaluate the method applied to see if it fits. If it does not, it should not be used.

Prepare any document following these guidelines:

• Use a font with serif's for the body text (Palatino Linotype, Times, etc.) - 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 - fancy layout does not ease the reading; it is what's in the document that matters - not the looks of it
• Three levels of headers are sufficient
• Use sans serifs fonts in headers (Helvitica, etc.)
• Use monospaced fonts for code fragments and the like (Courier, etc.)
• Make use of digital photos rather than wasting time on redrawing
• Figures, tables, drawings, etc. should be numbered continuously
• On each page, place a footer or a header that contains:
  • Project name - company name or team name and/or name of team members (for students)
  • Date of print
  • Page number / numbers in total
• Deliver documents either with the pages held together (for students)
  • with a staple in the upper left corner - preferable
  • in a binder that does 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 itself.

In Industry

In the industry, the process itself is less important and the focus is on the documentation of the developed. The documentation must be as complete and detailed as possible that it enables a colleague to inherit the project and continue the work. This requires that the documentation 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 put 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 reflects the observed problem.

Engineering and EUDP

EUDP describes an engineering development method. EUDP can be, and is, 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 itself.

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, meaning that a successor does not have to try out the dead ends just to find them impracticable in the current project.

Example of 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
• Quote

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
• Quote

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

• Meeting notes
• Plans
• Other relevant for the mentor

Epilogue

• Summary or conclusion

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