Documentation

From EUDP
Jump to: navigation, search

What

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

DocumentationAndWorkFlow.png

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, 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 options and argue for the pros and cons of these. Make a decision and document what caused the specific decision to be made. Any customer or developer who reads the argumentation should be able to accept the decision without questioning it, and begin work based on the decision 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 need 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.

At the bottom of this page, a complete collection of artefacts that an EUDP process can produce is shown. 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)

Use a standard diagramming tool, for instance Dia [3], and choose the UML or SysML templates.

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.

After having documented the project progress as described elsewhere on this page a hand-in technical report is written. The technical report is the report that the examiners will concentrate their effort on.

The progress and process documents are used in the day-today supervision where the supervisor teachers reviews the documents and give feedback concerning the work, progress and if corrections need to be performed in the way the work is carried out.

The technical report shall summarise the development work in such a way that it can be read without support from the progress and process documentation. Therefore the technical report shall start with a short introduction to what this project is about followed by a block by block description and concluded by a conclusion summarising the work that had been done.

Most of the text and figure inputs can be pulled from the progress or process documentation but are organised differently. For instance during development an initial architecture is gathered from the Launch Phase including the initial analysis and prototypes, if such is developed during the Launch Phase, further analysis is performed in one timebox and design and implementation is performed in a later timebox. In the technical document all these pieces are put together in a complete description of the particular block being analysed, designed, implemented and verified.

A suggested structure of a technical report can be:

  • Introduction
    • Description of the project in general
  • Requirements
    • Further description of the requirements where necessary in order for the reader to understand it
  • Architecture
    • Description of the architecture
  • Block 1
    • Describe the main points from the analysis, design and implementations
  • Block 2
    • ...

...

  • Conclusion on the project
    • Verification results
    • The current state and further work necessary is described

The Introduction section will take the reader into the projects scope.

The Requirements section pull the requirements as defined during the Launch Phase and includes subrequirements defined during development work.

The Architecture is the final architecture of the product, which typically is different from the architecture derived in the Launch Phase.

The Block N sections describes each block that the project has been divided into. The description includes analysis, design, implementation and verification setup.

The Conclusion section summarises the project and describes the state of the work - is it ready for production or should further development be carried out before the product is ready for production or delivery.

Throughout the documentation it is recommended to use the IEEE Citations Style [1].

Also keep in mind to keep the document size as small as possible without loosing the audience. Remember: Perfection is achieved not when nothing more to add, but when there is nothing more left to take away. [2]

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.

Example of Documentation Artefacts

Progress documentation
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
  • Risk analysis
Contracting
  • Development plan
  • Product acceptance
  • Quote
Realisation Phase
Strategy and planning
  • Risk mitigation plan
  • Development strategy
  • General verification plan
  • General deployment plan
  • General development plan
For each timebox (include necessary items from the list below)
  • 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 Phase
  • Customers general product accept
Evaluation
  • 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
  • Meeting notes
  • Plans
  • Other relevant for the mentor


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

Note: These documentation artefacts is used for the weekly supervision by the teachers, when performed at the university. Also note the even if you hand in the artefacts to a supervisor teacher and he/she reads it, there will be no writing for you, no proof-reading and/or no pre-exam approval - only guidance to where the document artefacts could be written better, sharper or eventually reorganised, etc. and probably also notes on what is missing.

References:

[1] IEEE Citations Style

[2] Antoine de Saint-Exupery

[3] The free diagramming tool DIA] (Installable on most OS'es.)