Projects
Table of Contents
Guidelines: Documentation of Demonstrators (Systems Engineering)
The objective of this documentation is to serve as the "Single Source of Truth." An external third party must be able to commission the demonstrator, troubleshoot errors, and implement extensions independently and without further inquiry.
1. System Overview (The "What" and "How")
Before diving into details, the overall concept must be clearly defined.
- System Architecture: A high-level block diagram of the entire system (including hardware, software, and interfaces).
- Bill of Materials (BOM): A complete list of all components including exact model designations, sources of supply, and (crucially!) version/revision levels.
- Interface Definition: How do the components communicate? (e.g., pin assignments, protocols like I2C or MQTT, mechanical flanges/interfaces).
2. Design and Development File
The goal here is to make the development process transparent and reproducible.
- CAD Data & Schematics: Storage in both native formats AND neutral formats (e.g., STEP for mechanics, PDF for schematics).
- Software Documentation: Code comments (Doxygen style recommended).
- README.md in the repository: Installation guide, dependencies (libraries), and build process.
- Design Rationale (Decision Log): Why was component X chosen? Why was solution Y rejected? (This prevents successors from repeating the same mistakes).
3. Operating Instructions (User Perspective)
To ensure the demonstrator can actually be operated.
- Commissioning: Step-by-step instructions (setup, power supply, required software).
- Operation: Description of functions and User Interface (UI) elements.
- Safety Instructions: Identification of potential hazards (heat, lasers, moving parts, electrical voltage).
4. Maintenance and Troubleshooting ("Successor Support")
This is the most critical part for the long-term sustainability of your project.
- Calibration: How is the system adjusted to ensure it provides accurate data?
- Troubleshooting: A table listing known symptoms, possible causes, and specific solutions.
- Test Protocol: Definition of a "Known Good State" (e.g., "LED 1 must light up green when voltage X is applied").
Golden Rules for Students (Checklist)
- No "Meaningful" Filenames: Avoid names like Final_Version_v2_actually_final.pdf. Use professional version control (Git) instead.
- Photos are Worth Their Weight in Gold: Document the internal assembly (especially wiring and PCB placement) before the housing is closed.
- The "Stranger Test": Give your manual to a fellow student from a different project. If they cannot start the demonstrator without your help, the documentation is insufficient.