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.
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.
Example
A complete example will be shown here at a later time.
Notes for further editing
Place holder for thoughts.
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
- 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
- <place holder for intelligent stuff to come :-) >
- Epilogue
- Summary or conclusion
Note: Items marked with dots are written or drawing artefacts.
Notes to remember when revising the pages
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
Remember that requirements, the architecture and other found in the Launch phase is what is going to implemented. A good idea is to refer back to the requirements, when during Realisation the specific requirement is selected for implementation. If the requirements are refined or even changed, because of deeper knowledge of the system-to-be, ensure, that the customer accepts this in writing or by signature - before rushing to implementation of the changed requirement.
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.
In the Use Case Analysis the involved objects/classes must be identified for each use case after the analysis and an updated SOD/Class diagram is the resulting artefact.
Identify the objects/classes involved after performing the Interface Analysis
