How To Use (START HERE!) - VTAstrobotics/Documentation GitHub Wiki

Contents

How to find stuff

For the GitHub Wikis, your two main tools to find docs are the Documentation Directory sidebar and the search tool above that under Pages. This is where all of the updated "intentional documentation" lives.

Intentional documentation is any document created with the purpose to teach.

In the shared Google Drive, the top-level folder has a Documentation subfolder. That subfolder has mostly been relocated here. Additionally, you can comb through the rest of the Google Drive folders for "unintentional documentation" which includes things like videos of past robots, papers, etc.

How to contribute docs

First steps

  • Use the templates (header template, page template)
  • Add your new page to the sidebar under the correct section.
    • This is done by clicking the pencil (edit) icon on the sidebar. It should be pretty intuitive from the other pages that exist.
    • This helps keep the pages organized and easy for others to find what they need, including FutureYou.
  • Similarly, add your new page to the corresponding header page.
    • Please take care to order them the same. Some of us have OCD.

Note: any red-colored links are broken, which either means the page does not exist (yet) or the page has changed names.

Adding Media (PLEASE READ THIS)

You can quite easily add an image by uploading it to the GitHub repository, but this eats up valuable GitHub repository space (5GB limit).

Instead, please link to media from Google Drive. There is an example for how to do this on the Markdown for Wikis page.

Tips, tricks, & avoiding pitfalls

  • For a link to a place within the same page, you can customize it, but the tag cannot have spaces.
  • SAVE! Commit early, commit often. You cannot save too much.
  • PLEASE choose your Wiki page names very carefully. I looked into it and it is currently impossible to change the name of the page without breaking all links to it. This means that every external link in existence would have to be updated, and that is not fun.

Cardinal sins

-Not using preview to verify your formatting works

image

  1. Not using the template.

  • Not finishing

  • Reiterate a page's title as a header. This is redundundant as GitHub shows the title on the page already.

  • Not writing an edit message.

  • BTW, here's the link to why uploading an image where text would work fine is terrible.