Repository navigation
Documentation
Good documentation is what allows a complex system to stay maintainable as the team grows and changes. Not everyone will work on every subsystem, and people will rotate on and off tasks — documentation ensures that whoever picks something up next has everything they need to get up to speed and keep moving.
Think about what you wish you had known before starting your task. Some useful things to capture:
- Unique problems or surprises — anything that took longer to figure out than it should have, or that wasn't obvious from reading the code.
- System context — write for a developer who is technically capable but knows nothing about this particular subsystem or topic. Don't assume prior familiarity.
- External packages — if your work depends on a third-party package or library, briefly explain what it does and how it's being used in this context.
- Diagrams — include these wherever they add clarity. Flow diagrams, architecture diagrams, data flow diagrams, and state machines are all fair game.
- Code snippets — only include these when they directly support something you're explaining. The documentation complements the code; it isn't a substitute for reading it. Feel free to be as technical as the topic demands. This is developer-facing documentation.
Below is a starting point for documenting a subsystem or a specific technical topic (e.g. "Drive System").
Author(s):
Last Updated:
A short paragraph describing what this subsystem or topic is, what problem it solves, and where it fits in the broader system.
Any prerequisite knowledge or context a developer would need before diving in. Link to relevant wiki pages, external documentation, or standards where appropriate.
Describe how this subsystem is structured. Include a diagram here if applicable — architecture diagrams, data flow diagrams, and component diagrams all work well.
Explain any domain-specific concepts, design decisions, or non-obvious behaviour that a new developer needs to understand. This is a good place to explain the "why" behind decisions, not just the "what".
List any third-party packages or libraries used, with a brief explanation of what each one does and how it's used here.
| Package | Purpose |
|---|---|
package_name |
What it does in this context |
Document anything that caused unexpected problems, edge cases to be aware of, or things that are easy to get wrong. This section is especially valuable for future developers.
Links to datasheets, ROS documentation, papers, or any other external references that are relevant.