Documentation

Documentation is essential to the continuity of any long-term project that passes through the hands of many engineers, and our project team’s controls software codebase is no exception. There’s a common saying in the software field: “good code is its own best documentation.” While it’s true that succinct, idiomatic, commented, clean code is tantamount to having a maintainable codebase, that saying misses a very important dimension. A project on the level of sophistication and domain-specific knowledge as ours, that meets new engineers and says goodbye to others every single year, needs strong documentation to help introduce each system to new eyes.

The controls software is broken down into different components called nodes, and there are two kinds of people who will use each node - consumers and maintainers.

• Consumers see each node as a box with input and output. They feed it certain input, and expect certain output in return. They tell the arm to move to a certain position, and they expect the arm to move. They might not care how the arm moved. They just need to know how to move the arm, and this should be well-documented.

• Maintainers develop the inner workings of the node. They are the ones who turn that aforementioned input into the expected output. They define what input they need, and decide how to implement the desired functionality. They need to know how the node works, and they need to know about all the decisions that went into the development process up to this point. For them, we have the concept of the DEEP DIVE - a detailed commentary of how the code works, with relevant links to external documentation and descriptions of important concepts where necessary.

Certainly, a maintainer of one node can be the consumer of another; for example, you may be developing a new arm control interface that needs to hook into the existing arm node. Also, while you may be maintaining a node now, someone else will eventually have to take over. For these reasons, it is critically important that you craft strong documentation for all your contributions to the Rover Controls Software codebase.

• Contributing
  • Introduction
  • Compiling
  • Adding Pages
    • Adding a Page to an Existing Section
    • Creating a New Documentation Section
  • Formatting
    • Headings
    • Text Formatting
    • Hyperlinks
    • Code Blocks
    • Images
    • Admonitions
  • Linking C++ Docs
    • Embedding Entire Classes
    • Embedding a Single Function
  • Further Reading
• Python and C++ Docs
  • Using Comments
  • Python Documentation
  • C++ Documentation
• Documentation Deep Dive