Documentation Tutorial

Table of Contents

1. Overview
2. Types of Documentation
   a. Software
   b. Mechanical
   c. Electrical
   d. GitHub Wiki
   

Overview:

This tutorial provides a general overview of documenting research work in the Olin Robotics Lab. Documentation is important both to the researcher and the organization, as it enables the collective gain of institutional knowledge and provides a way for a student's work to continue to be meaningful after they have graduated. Documentation is also useful to reference when asked about previous work. In order to create useful documentation that is easy to reference and maintain, however, several standards must be followed.
The following are the general types of documentation used in the Robolab. For more information about each, see the links in the above table of contents.

• Software Documentation: docstrings, in-line comments, Readme files.
• Hardware Documentation: design intent, list of materials, manufacturing processes, CAD files and drawings.
• Electrical Documentation: power diagrams, data diagrams, power usage tables, bills of materials.
• Github Wiki Documentation: software and firmware documentation, platform tutorials.

GitHub Wiki Documentation

The majority of software/firmware documentation in the lab is housed in GitHub Wikis. Each repository in the Olin Robotics Lab has a wiki attached to it that can be accessed through the link near the top of the repository's main page. The following steps detail how to create a new wiki page that is useful and easy to reference later.

1. Check for Page
   You should have done this before you started researching the concept, but ensure that no other page containing similar information exists on the wiki.

2. Create New Page
   Create a new page using the green "New Page" button in the upper right of every Wiki page.

3. Choose Title
   Title your page with a short (2-3 word) topic detailing the content

4. Copy Template
   The wiki has a template wiki page to help you with formatting and determining what information to place in your documentation. Go to the page, edit it, copy the markdown, and paste it into the body of your new page. (link)

5. Write Documentation
   If you are documenting a process or a build, detail the steps you took such that someone with no prior experience can follow them (See the toolbar when writing for how to properly use Markdown). If you are documenting a concept, detail the general ideas of the concept and add some notes on practical application. Write the document you wish that you had when starting the work. Check out the reference links for some useful Markdown basics. (reference) (reference)

6. Add Links If you found any online documents helpful, link them using the link button in the Markdown toolbar. If you referenced any other pages of this or other Wikis, include a link to the page by copying and linking the URL of the page. If you want to link to a heading on the page, click the link icon that shows up when you mouse over the heading on the respective page and copy the resulting URL.

7. Add Images
   If you have taken or could take images that are useful for understanding your work, follow these steps:

• 1a. If your picture is on your local Disk:
  • i. Clone the respective repository, place image file in images folder, commit, and push.
  • ii. Navigate to the images folder of the repository and use the "Upload Files" button to upload your image file.
• 1b. If your picture is online:
  • i. Copy the link to the image (not the website, the image itself)
• 2a. Use the image icon in the toolbar, or use this syntax to put the image into your markdown file: ![minion image caption]https://github.com/olinrobotics/olinrobotics.github.io/blob/master/images/minion.png)
  
• 2b. To resize the image, instead use this syntax and replace '200' with the desired image width. <img src="https://github.com/olinrobotics/olinrobotics.github.io/blob/master/images/minion.png" width="200">

8. Add Tables
   Go to the Markdown Tables generator (link), input your table information, and paste the resulting information into your markdown file. If you deal with multiple tables, it might be a good idea to copy the tables into a spreadsheet and save it to the repository.

9. Save Page
   Commit changes and save the page. If you would like, submit a quick message stating what you documented so that if later readers have questions about a piece of documentation, they know who added it and when.

10. Linking
    You're almost done! The last step is to make sure future research students can find your work. Copy the link to your page and paste it into any location you feel is important for people to be able to find it. If it's a fairly high level concept, it might belong in the sidebar Table of Contents. It also might link from a platform-specific page. If you are unsure, ask your thrust leader.

Sources

• Markdown Basics - Quick reference sheet for basic Markdown skills
• Mastering Markdown - A different Quick reference sheet similar to above
• MediaWiki internal link formatting - How to format links to other wiki pages within a single wiki
• Markdown Anchors - How to format links to Markdown headers within a single wiki page
• Markdown Table Generator
• Markdown Table of Contents Generator