watonomous.github.io

1. Electrical Division
2. Electrical Division Home
3. Radar Driver Group

[ Electrical Division : Radar Driver Documentation Conventions ]

Created by [ Frank Yan], last modified on Apr 20, 2020

---

[]{.aui-icon .aui-icon-small .aui-iconfont-info .confluence-information-macro-icon}

Most of the documentation conventions are taken from the sensor-interfacing page (props to Rohit for making that). However, there are some key differences for the radar driver group.

Table of Contents

• When to Update Documentation
• Tables of Content
  • Inserting Tables of Content
• Document Abstract/Overview
• Styling
• Code Blocks
  • Inserting Code Blocks
  • Code Block Conventions
• ToDos
• Comments
• Info bars
• Old Documentation
• Miscellaneous Styling Conventions

When to Update Documentation

Documentation is not the most interesting thing to do but it is necessary and is super useful for future members. Whenever your code gets merged into master, you should update any related documentation to your code that got merged into master. This includes code blocks, info bars, and any related macros. For small changes such as whitespace changes, grammar/spelling corrections, or formatting there is no need to notify watchers. If the change is rewriting a section, adding a new section, or anything of significance, select notify watchers to let the person in charge know of the change you made. Once the person in charge approves of it, then you can update the JIRA ticket to 'Done'.

Tables of Content

Inserting Tables of Content

• 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.

Document Abstract/Overview

• 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/Overview" and is styled as "Heading 1"

Styling

• 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.

Code Blocks

Inserting Code Blocks

• The Code Block macro can be accessed by hitting the "+" located on the upper toolbar when 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.

Code Block Conventions

• If you're using a code block to specify a command which you're running from 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 "#".
• Make sure you select the correct syntax for the code language if it is in C++, make the syntax C++ for the code block.
• Code lines are not necessary but are nice. However, if the code frequently changes, you will have to update the code lines so it is up to you if you want to put in the work.

---

$ roslaunch radar_driver all_radar.launch ——————————————————————————————————————————————————————

ToDos

• 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 else's 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 (Your name): Finish this section of the page.***]

Comments

• Add inline comments by hovering over the text you want to comment on. Comments are used for flagging information that you think needs to be checked. If something is unclear, needs to be reworded, or is not formatted properly then add a comment describing why you commented to let the person who was working on it know so they can fix it. 
• Once the issue has been resolved, resolve the inline comment.

Info bars

• Info bars are useful if you want to emphasize a point/bring attention to something they should know about. They can also be used as a reflective remark. To insert one click on the plus sign when you are editing a document and the "Info"section should be there. 

• If you are emphasizing a point or bringing attention to extra information then it should be placed before the section you are writing about. For example if a person is writing about radar networking then an info bar could be:

  Info Example 1

  []{.aui-icon .aui-icon-small .aui-iconfont-info .confluence-information-macro-icon}

  Make sure you are on the right network!

• If you are using a reflective remark then it should be placed after the section you are writing about. For example if a person is writing about SNR thresholds then an info bar could be:

  Info Example 2

  []{.aui-icon .aui-icon-small .aui-iconfont-info .confluence-information-macro-icon}

  More testing needs to be done with this as there is not enough information about this!

Old Documentation

The radar-driver group does not have a need for old documentation. This is because the majority of our older stuff is simply outdated. For example anything that says "ARS430" is outdated as the radar-driver group has set up their own repo and  is no longer going to use "ARS430" for their code. It wouldn't make sense to go back to using ARS430 if we set up a new repo for radar-driver. Delete any documentation that is outdated or incorrect and update it with the correct information. If you are unsure if something should be deleted, ping the radar driver group in Discord.

Miscellaneous Styling Conventions

• A Horizontal rule should be inserted between the document title and the rest of the document.
• Horizontal rules can also be used to divide sections into parts or break up the section.
• Filenames should be italicized. (Example: ~/.bashrc)

\

\

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

Atlassian