diff --git a/Contributing.md b/Contributing.md new file mode 100644 index 0000000..fd2ffc4 --- /dev/null +++ b/Contributing.md @@ -0,0 +1,104 @@ +# Contributing to SciGuides + +SciGuides is a ***living document***. Both it and [SciGuidesRobotBase](https://github.com/SciBorgs/SciGuidesRobotBase) should be updated yearly to reflect current team programming standards and all changes to WPILib, external docs, and vendor libs. + +Members of 2265 should feel free to add or modify any contents of SciGuides and its template repository as needed through a PR to improve the learning experience for team members and JV students. + +## Getting Started + +If you have changes you'd like to make, discuss with a mentor or programming leadership before making them. + +Use any editor of your choice, whether that be VSCode, Obsidian, or whatever else. + +All changes must undergo the review process as listed below. + +1. Please create your own branch and pull request (PR) to make changes from. +2. Request a review from relevant members of leadership, and respond. +3. Repeat step 2 until approval. + +Do not open duplicate pull requests or issues; check that others have not already made or discussed your desired request. + +## Creating content + +See the [summary](#tldr-too-long-didnt-read) for quick reference. + +### Guidelines + +We hope to maintain a quality standard for our work, so all writing should roughly follow the below guidelines: + +- Don't reinvent the wheel. + - It's a waste of time to recreate and maintain documentation that others have already created in-depth, so we heavily reference existing documentation from vendors, libraries, and WPILib. + - Minimize what must be changed from year-to-year! Avoid restating existing documentation; we recommend including only a few sentences for the purposes of introduction, before linking to it. +- Experiencing is the heart of learning. + - It is our firm belief that people learn best when actually **writing** and **seeing** code and images on the screen. Code examples, code examples, code examples (and the occasional image and gif, too!) + - In the same vein, aim to be as concise and to-the-point as possible. Gigantic text walls are daunting and difficult to follow. +- Make sure your guides are **functional** and **working**. + - The code created by following your guide should actually work. For projects, write the code and copy-paste the necessary code examples into the doc. + - Even better, you may want to write the code first and base your doc on the steps you take. It's good practice, I swear! +- Keep to typical standards of documentation. + - Please look over your grammar, punctuation, and spelling before submitting your PR for review. At a baseline, errors should not obstruct understanding or behave as a distraction. +- These guidelines are not immutable. + - Use your own discretion (or that of your fellow team members) to determine what is best for this repository to achieve its goals. + +#### Specifics + +For GitHub & editor compability purposes, all comments should be formatted like so: +`[comment]: # (YOUR-COMMENT-HERE)` + +### Style & Writing Tips + +There are a few boxes to check when writing engaging, cool pages, especially not having lengthy paragraphs of text! + +#### Fundamentals + +Prioritize readability. +- Break down complex paragraphs and explanations into smaller parts; use identation and [whitespace](#spacing-techniques) to your advantage. +- Use [GitHub markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) features to emphasize and guide certain parts of the doc. This includes headings, lists, separators, footnotes, etc. +- Be concise and to-the-point with your words. +- Avoid repetition unless it just makes sense. + +Keep in mind your target audience; introduce complexity bit-by-bit for beginners, and relax for advanced students. + +To the best of your ability, anticipate common learning mistakes or pitfalls and address them so that in-person mentors won't have to. + +#### Spacing Techniques + +A good idea is to put yourself in the shoes of a brand new robotics student learning the ropes. If you were them, would you rather read this... + +--- + +*Java, the workhorse of enterprise software, often feels like a language stuck in the past despite its incremental improvements. Its verbose syntax can make even simple tasks feel like wading through boilerplate code, with developers writing lines upon lines just to declare objects or handle exceptions. The "write once, run anywhere" mantra sometimes translates to "debug everywhere," especially with JVM inconsistencies across environments. Performance, though respectable, often pales in comparison to more modern, lightweight languages, and its garbage collection, while helpful, can cause unpredictable hiccups. Java's ecosystem, though vast, can be overwhelming, with libraries and frameworks that vary wildly in quality. Despite all this, it remains entrenched, leaving developers with no choice but to navigate its quirks for the sake of legacy systems and industry demand.* +###### Generated by GPT-4o. Does not represent the opinions of the team nor any related individuals. + +--- + +or this...? + +--- + +*Java, the workhorse of enterprise software, often feels like a language stuck in the past despite its incremental improvements.* + +*Its verbose syntax can make even simple tasks feel like wading through boilerplate code, with developers writing lines upon lines just to declare objects or handle exceptions. The "write once, run anywhere" mantra sometimes translates to "debug everywhere,"especially with JVM inconsistencies across environments.* + +*Performance, though respectable, often pales in comparison to more modern, lightweight languages, and its garbage collection, while helpful, can cause unpredictable hiccups.* + +Java's ecosystem, though vast, can be overwhelming, with libraries and frameworks that vary wildly in quality.* + +*Despite all this, it remains entrenched, leaving developers with no choice but to navigate its quirks for the sake of legacy systems and industry demand.* +###### Generated by GPT-4o. Does not represent the opinions of the team nor any related individuals. + +--- + +I'd like to bet you chose the second selection. And that's because you can easily pick out and read it! Each new topic is put on its own, allowing for simpler referencing and understanding. + +So, if you find yourself writing something too long (which you should avoid regardless), space it out a bit! Especially for instructions. + +## TL;DR (too long; didn't read): + +- Create a branch and pull request of your own to add features. Your changes will be merged after looping through the review process. + - Consult with leadership before making any changes; you wouldn't want to make unnecessary additions! +- Instead of wordily explaining concepts on your own, reference external docs and sources for **in-depth information**. + - A good balance we follow is to introduce a concept / process with a few sentences before linking to more in-depth documentation. +- Keep your documents readable - no text walls (they hurt the eyes!) + - Take advantage of text-spacing techniques with newlines, codeblocks, images, & other styling elements (like this list!) +- See the specific [style section](#style) above. diff --git a/README.md b/README.md index e69de29..44df4c6 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,21 @@ +# SciGuides + +Welcome to SciGuides, a repository made by FRC Team 1155 to gather all of our experience and knowledge for public and internal use. We thank 2265, our sister team, for their contributions. + +## Usage + +SciGuides is project-based, containing [tutorial projects](/projects/README.md) and [reference sheets](/reference-sheets/README.md) aimed at guiding readers towards a high level of competency around FRC code. + +It can be used to teach material, practice writing robot code, reference information, or pass down generational knowledge[^1]. It may be highly opinionated and team-personalized as a result. + +[^1]: As we do not have programming mentors, this repository serves as the only way to pass down and retrieve generational knowledge. In the event of another lockdown, this repository will be vital in restoring team skills. + +This repository also functions as the curriculum of our school's JV robotics program. + +If you spot any mistakes, please let official team programmers know! Feel free to create a GitHub issue or notify a mentor. + +## Contributing & Updating + +SciGuides is a ***living document***. It should be updated yearly to reflect the latest changes in WPILib, vendor APIs, team practices, and more. + +See [Contributing.md](Contributing.md) for specific directions on what we're looking for. diff --git a/archive/README.md b/archive/README.md index ff47d21..0e53b7a 100644 --- a/archive/README.md +++ b/archive/README.md @@ -1,3 +1,5 @@ +This is a primitive version of SciGuides created from 22-24. JV did not exist at this time; its purpose can be seen below. + # SciGuides Welcome to SciGuides, a repository made by FRC team 1155 to gather all of our experience and knowledge for public and internal use. diff --git a/projects/README.md b/projects/README.md index 6ad5644..2f1c77e 100644 --- a/projects/README.md +++ b/projects/README.md @@ -1,13 +1,28 @@ +# Projects + +This folder contains all of the projects you'll be completing. + +There are 3 levels of projects; they should be completed in descending order, but can be skipped if your knowledge is up to par. Regardless, each section will serve as great practice. + +1. [Introduction to Programming](/projects/intro-to-programming/README.md) + 1. [General Programming](/projects/intro-to-programming/Programming101.md) + 2. Java [101](/projects/intro-to-programming/Java101.md) and [102](/projects/intro-to-programming/Java102.md) +2. Basic Differential Drive + 1. Basic Arm Bot / Basic Shooter Bot +3. Swerve Bot + 1. Advanced Arm Bot / Advanced Shooter Bot + ## Best Practices As you go through these tutorials and projects, here are some practices you should try to follow: + 1. Go through all example code thoroughly until you understand it. If it's not clicking, ask for help. -3. If there's ever a concept that you don't understand, ask for help! -4. Do the work **on your own**. You can talk to your friends about concepts, but for the most part, go at your own pace, and try to understand the concepts on your own before asking for help. - 1. Some projects are explicitly made to work as group projects. In those situations, you can of course work with a group, but still make sure that you're writing your section on your own! -5. When you ask for help, you have a few options: - 1. Maybe there's someone you're working with who you can ask, and if they know the answer, that's great. - 2. Ideally, you also have someone who's a more experienced programmer who can help you when you need it. - 3. If you find yourself without anyone who can help you, here are a couple options: - 1. Look it up - 2. Ask Claude or ChatGPT. Be careful not to use a prompt that will cause it to give too much away --- if it tells you all the answers, it will be harder to learn. And I can't guarantee that it will always give you great answers. But LLMs are good resources to have when you don't have anything else. \ No newline at end of file +2. If there's ever a concept that you don't understand, ask for help! +3. Do the work ***on your own***. You can talk to your friends about concepts, but for the most part, go at your own pace, and try to understand the concepts on your own before asking for help. + 1. Some projects are explicitly made to work as group projects. In those situations, you can of course work with a group, but still make sure that you're writing your section on your own! +4. When you ask for help, you have a few options: + 1. Maybe there's someone you're working with who you can ask, and if they know the answer, that's great. + 2. Ideally, you also have someone who's a more experienced programmer who can help you when you need it. + 3. If you find yourself without anyone who can help you, here are a couple options: + 1. Look it up + 2. Ask Claude or ChatGPT. Be careful not to use a prompt that will cause it to give too much away --- if it tells you all the answers, it will be harder to learn. And I can't guarantee that it will always give you great answers. But LLMs are good resources to have when you don't have anything else. diff --git a/reference-sheets/README.md b/reference-sheets/README.md index e69de29..e8b9dee 100644 --- a/reference-sheets/README.md +++ b/reference-sheets/README.md @@ -0,0 +1,6 @@ +# Document Reference Sheets + +This folder contains guides that overview key topics and practices on SciBorgs Programming. There are two types of docs: + +- Docs that introduce readers to essential concepts used in FRC programming, with links to official WPILib and vendor documentation for detailed information +- Docs that guide or teach readers to perform essential tasks that are not / cannot be in project formats