watonomous.github.io

[ Electrical Division : Sensor Interfacing Documentation Conventions ]

Created by [ Rohit Kochhar], last modified on Mar 30, 2020

If you're updating old documentation, please do not delete anything. Instead, update it as follows:
1. Place a horizontal rule between your documentation and the old documentation by clicking the "+" and selecting "Horizontal rule"
2. Underneath your Horizontal rule, add "Old Documentation", and make sure it's formatted as a "Heading 1" by highlighting it and selecting the dropdown located on the far left of the upper toolbar.
3. Make sure any titles that are located in the Old Documentation section are taken down a level, so that it displays as a sub-section in the Table of Contents.

The first thing that should be included in documentation should be a Table of Contents. To insert a table of contents:
1. Add in "Table of Contents", styled as a "Heading 1"
2. Insert a table of contents by hitting "+" located in the upper toolbar, and then selecting "Table of Contents" from the dropdown.
3. That's it! It becomes formatted automatically as you use the correct styling.

Underneath the table of contents, include a few bullet points which outlines the document, touching on what is discusses and why we need it. Make sure that this section is titled "Document Abstract" and is styled as "Heading 1"

Properly styling our titles ensures that our table of contents is formatted correctly, which then lets a user navigate the documentation seamlessly. To edit styling:
1. Highlight whatever you want to style
2. Select the styling that you want from the dropdown located at the far left of the upper toolbar.
3. You can sanity check that your styling is good by saving the file that you're editing at anytime and checking the table of contents, if it is divided into sections as you like, you're good, otherwise play around with it a bit to get what you want.

The Code Block macro can be accessed by hitting the "+" located on the upper toolbar when you're editing a confluence document. Once you hit the "+", select other macros, code block should be selectable from the menu it takes you to, if it isn't just search "code block" and it will appear.
After selecting code blocks, just hit "insert" and it will add an editable field into your document.

If you're using a code block to specify a command which you're running from the Rugged terminal, prefix it with a "$" followed by the command that you're executing, if you want to add a single line comment explaining what the command does, prefix it with a "#".

$ sudo arp-scan --interface=enp4s0f1 -l        # Lists all network connected devices

If you are listing ROS topics (which we will most likely do a lot on our team), you can use a code block to make the topics easily distinguishable and easily readable.

/camera/left/image_color
/camera/centre/image_color
/camera/right/image_color

ToDos are a useful way of flagging documentation so that it is clear what we need.… ToDo.
ToDos should be inserted wherever you feel like they are needed.
If you're adding a ToDo that requires someone elses attention, you should contact them sooner than later to ensure that it gets resolved.
After declaring the ToDo, add the name of whoever needs to resolve it in brackets so that they can easily locate it.
ToDos should be prefixed and suffixed with three asterisks ***, and should be short and succinct.
Example: [***ToDo (Rohit): Insert diagram detailing physical wiring with PoE boxes.***]

A Horizontal rule should be inserted between the document title and the rest of the document.
Filenames should be italicized. (Example: ~/.bashrc)
If you're referencing variables to a command, bolden it (Example: left_camera_serial)

Document generated by Confluence on Nov 28, 2021 22:40