-
Notifications
You must be signed in to change notification settings - Fork 6
The README Guide
All of our code should have a README.md file associated with it. The README should have all the
required sections listed in this guide
in the order and formats shown here.
Should specify what sensor the program is written for
Ex:
Code for the AS7265x Spectral Triad Sensor
This section should include a high level functional description of the software.
All the channels that the program is subscribed to and publishes to should be listed here along with a link to the rover common LCM struct
Ex:
Drive Velocity [subscriber]
Messages: DriveVelCmd.lcm “/drive_vel_cmd”
Publishers: onboard/teleop
Subscribers: onboard/odrive
If the hardware has a watchdog timer, its time out period should be listed here
This section should contain all instructions and relevant commands for usage, including hardware specs
(hardware required, what microprocessor the hardware should be wired up to, etc) and the configurability interface (if there is one)
Type out all the LCM commands using markup code syntax `( $ command )`
Explain all error handling that the program does in this section, listing the off nominal behavior as well as what is seen on the
users end as a result
Ex:
Odrive Errors
If the odrive throws an error, odrive_bridge will tell it to reboot. The error will be displayed in the terminal and the state
will be displayed as ErrorState. Depending on which odrive this happens on, either the front or back motors will be unresponsive
for a minute until the odrive finishes rebooting. The state will automatically change from DisconnectedState to Armed
upon completion.
This section should contain all relevant commands for debugging the code or debugging electrical/mechanical issues.
For motor controllers, how to disable the device should also be listed here.
This section should contain a list of all common problems that can occur when using the code, as well as how to fix them. Each error
should be its own (h4) header, with a more detailed description below along with the relevant steps needed to fix it.
This section should have a list of the remaining items needed to be finished for the code. The todo (and later on completed todo)
items should be listed using this markup syntax:
[x] item 1
[ ] item 2
[ ] item 3
They should be updated periodically during the duration of the project. If the project is more collaborative, the todos should
include detailed descriptions so that other developers can more easily understand and implement what needs to be done.
Anything else relevant that does not constitute its own section. For example the version of python this code has been tested
with, or a link to the sensor data sheet if it has one.
This is a very basic list of what needs to go into a README. Obviously projects might have other more specific things that
should be included in their READMEs, so feel free to add other sections as needed. The odrive_bridge README, for example,
has a separate How To Set Up An Odrive section because this process is quite long and unique.
Make sure that the README is ordered exactly as everything is in this guide (with the exception of any Other Sections,
which can go wherever they are deemed as relevant to be). The Title should be formatted in markdown like this:
Title
---
All headers (h3) should be formatted as
### Header Name
All subheaders (h4) should be formatted as
#### Subheader Name
Etc for sub...subheaders
To make a new line in a README file use \
To input a line of code format the text like this ` code `
To embed a link [text](url)
To embed an image 
For all other markdown questions you may have check out these pages!
Here is an example of the Spectral Sensor README to refer to!
Additionally here is the link to the google doc version of the README guide.