frc6506 / docs

Programming team documentation project including Java, WPILIBj, git, GitHub, GitHub Desktop and GitHub org administration.

docs

Attempt to create team docs.
If I actually wrote articles more than once every 3-4 months or someone else also wrote articles, it might actually be very useful by now.

If you would like to help, see CONTRIBUTING.md

Updated 20210510T1615 PDT

docs's Issues

Move repo setup guide to general

(out of admin)

More git resources

https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/GitHub

Clarity to improve new person discovery- index links

The learn programming link in the index offer multiple languages. Maybe mention Java in an introduction or create a new page?

Tutorial for JDK not detected by VS code?

Maybe add?
(in generic VSCode setup)

Markdown linter

Well I tried one but its not working out of the box.
See PR #2

Add useful NI roboRIO documentation

NI roboRIO user manuel: https://www.ni.com/pdf/manuals/374474a.pdf
NI roboRIO specs document: https://www.ni.com/pdf/manuals/374661a.pdf

Add resource's page and contents

https://docs.google.com/document/d/1pr0j-VJTJZn2HFQLNxXBAPovNQQqOaRDpBroRyJcsTw/edit

Easier way to specify python version?

%USERPROFILE%\AppData\Local\Programs\Python\Python37\python.exe
in https://frc6506.github.io/docs/advanced/characterization.html and https://github.com/frc6506/docs/blob/master/advanced/characterization.md
to
py -3.7

See https://stackoverflow.com/questions/45137395/how-do-i-upgrade-the-python-installation-in-windows-10/55069640

Make sure all docs page goes with presentation info

https://docs.google.com/presentation/d/e/2PACX-1vRZlrW9X5Tn2a9EdpZ2iVTtD4TPZJUqQlTI4D0ThXZwhgwMI8DkeJMmreyRZ4Eh2ZlNa5eA1I8kLV7d/pub?start=false#slide=id.g7c4f60a2f9_0_7
Maybe update presentation as well?

Finish the GitHub Desktop Tutorial

https://frc6506.github.io/docs/quickStart/gitHubDesktopTut

Mention updating the assignee list for the dependebot action?

Time to update spell check action?

Looks like it's at 0.17.0, although it says update not required
https://github.com/rojopolis/spellcheck-github-actions/releases/tag/0.17.0

https://github.com/rojopolis/spellcheck-github-actions/releases

Note: It's currently working fine.

Add explanation of markdown modification lists and vs code extension spell check whitelist to contributing file

Actually plan out FRC coding introduction

Paradoy and/or links to actual github docs

https://docs.github.com/en

• github.com
• organizations
• code security
• github actions
• github packages
• delvopers
• github isngies
• github discussions
• codespaces
• github sponsors
• buildign comujintiems
• github pages
• eduacation
• github destkop
• github cli
• codeql

Add fancy PDF generation

See https://www.google.com/search?q=github%20action%20markdown%20to%20pdf&ie=utf-8&oe=utf-8&client=firefox-b-1-m
and https://github.com/marketplace/actions/publish-markdown-as-pdf and https://github.com/shrink/actions-document-sign.

• [] as build artifact (Demo)
• on manual release
• on automatic release at end of day if there has been a commit that day
• push to master instead of build artifact all the time

Move PDF to documents folder

Java learner resoruces

• CodeHS
• https://programmingbydoing.com/
• Code academy

Best way to quickly teach important Java concepts (in under a moth) while not being boreing?

Markdown Syntax

The markdown lint action will now show poorly/inconstant formatted markdown. All the files should really be standardized to something (the config can be changed)

I have davidanson.vscode-markdownlint installed in VS Code.

Checkout FTC Team 14969 workshops

It appears to be FTC oriented :(
https://drive.google.com/drive/folders/1HeM5ZhlBqQve5hpt9tH9mqwzhfd3gpG4?usp=sharing

Not sure about it.

Mention eamodio.gitlens VSCode extension in docs?

eamodio.gitlens

Add Hardware status light docs link

• PDP
• VRM
• We dont really use the nuematic thingy

• RoboRio
• Radio
• Network Switch

• Spark
• SparkMax
• TalonSRX
• VictorSPX
• NavX 1
• NavX 1 w/ cover

Find or create cheat sheet for beginners, better teaching idea?

Also, for teaching maybe a practice project using it.
Maybe it could get progressively more difficult
eg:

• variables for 'drive-train' speed -->
• maybe user input -->
• loop to update variables -->
• actual WPLiubj timed robot -->
• WPLibj command based code -->
• ...

Add Link to SparkMax install website

(On the index page)

Consider just-the-docs jeykel compatible theme

https://github.com/pmarsceill/just-the-docs
It adds a sidebar for easy finding things (similar to read the docs).

Consider adding an action to check grammar and writing quality

With the write good action.

Why does no one like passive voice/

Link to cheat sheet in index

update to 2021-22 GitHub Presentation

https://docs.google.com/presentation/d/1C4kl43SWPtGlhXZhZaKj87lJZqm-z4JerMFx0MdTp98/edit#slide=id.g45a200e9bd_0_0

(referenced in the files for git)

PDF generation vs. GitHub pages conflict in regards to the Java OR operator inside a mono-space code format indicator inside a table

From /Java/JavaCheatSheet#288:

Note about the logical OR operator: The operator for OR in Java is ||, eg: A || B. This may be incorrectly displayed below do to a conflict with the markdown table symbol |. It appears that the markdown conversation VSCode extension requires an escape character (\), while GitHub pages does not.

Find links for limelight docs/tutorial

index.md:81
[Vision Processing with Limlight]()

Try to stick to RFC2119 terms to Indicate Requirement Levels

https://datatracker.ietf.org/doc/html/rfc2119
Add link to contributing
I don't think this is a big issue.

Image action not working?

Probably not that important. Might fix later or something.
https://github.com/calibreapp/image-actions

Make note about codespaces

• codespaces
• also school's vm
  (for people with chromebooks)

Investigate easy installer for basic Java

https://code.visualstudio.com/docs/java/java-tutorial

add admin docs (checklist)

• Overview
  • Admin responsibilities
• Quick Start Guides
  • membersQuickSetup
  • orgMaintenanceGuide
  • repositoryQuickSetup
• Summaries
  • [-] Organization Homepage
  • Repositories Tab
  • Packages Tab
  • People Tab
  • Teams Tab
  • Projects Tab
  • Settings Tab
• Repositories tab
• People Tab
• Teams Tab
• Settings Tab
• OrgManagement
  • [-] orgDiscount
  • teamCleanup
  • [-] orgOwners

Explain .gitignore

• Mention setting preset to Java on repo cration
• Metnion what types of file should be commiteed

Write gitHub desktop tutortial

The page https://frc6506.github.io/docs/quickStart/gitHubDesktopTut only contains links to official GitHub docs, which contain links to more detailed docs (too detailed).

Also find old presentation to help.

Add link to new Mooc course

https://java-programming.mooc.fi/

Add electrical system layout link

https://docs.wpilib.org/en/stable/_images/frc-control-system-layout.svg

.txt files not spell checked by action

Replace links to Slack with actual files

• Upload Tomb of Secrets and give it a description
• Maybe others?

Also, Slack hides the oldest messages and access control is not set up to for infinite availability to team.

Bad Spelling

See Actions

Add diagnostics and troubleshooting guide

• CTRE PDP will get no CAN comms unless robot code or diag server is connected
• Other
• Find premade one?

Update with latest workshop materials

also the control system presentation

Edit w/ checklist:

• presentation 2
• control systems presentation

Investigate 2021 and 2022 Command-based changes

Add links to explanation
And add links to explanations for any unusual/adv Java syntax

Start linking GitHub docs for admin stuff as well as FRC docs for normal stuff

Allot of the custom documentation for admins could be adapted from already existing docs and adding notes instead of recreating from scratch. They should definitely be linked. This would especially be good for more advanced stuff. However, for quick guides, it might be easier to follow simply do one file? *shugs*
https://github.com/github/docs
https://docs.github.com/en/organizations
https://docs.github.com/en

Add link to CTRE Phoenix Reference

Add link to WPLib-j JavaDoc

https://first.wpi.edu/wpilib/allwpilib/docs/release/java/index.html

Add dedicated firmware section? & configuration & code snipet at the same time

Most of it should already be listed but could make seperate doc to simply index

• PDP (updates rare)
• VRM?
• We dont really use the nuematic thingy

• RoboRio (constant updates)
• Radio (constant updates)
  • Also mention ports
• Network Switch?

Mention code snippets & relevant libaries:

• Spark (no firmware)
• SparkMax- Vex thingy
• TalonSRX- Phonix
• VictorSPX- Phonix
• NavX 1- Kauii Labs
• Limelight
• RPI

Clarity to help new people- Introduction FRC Coding in Java

Make clear next and previous links at the end instead of effectively nesting instruction lists