From d20c95e2741020739938c626e586b881247e9bfc Mon Sep 17 00:00:00 2001 From: Kishan Date: Sun, 6 Oct 2024 22:49:17 -0400 Subject: [PATCH 1/7] move intro our of projects --- .../intro-to-programming => intro-to-programming}/Java101.md | 0 .../intro-to-programming => intro-to-programming}/Java102.md | 0 .../Programming101.md | 0 {projects/intro-to-programming => intro-to-programming}/README.md | 0 4 files changed, 0 insertions(+), 0 deletions(-) rename {projects/intro-to-programming => intro-to-programming}/Java101.md (100%) rename {projects/intro-to-programming => intro-to-programming}/Java102.md (100%) rename {projects/intro-to-programming => intro-to-programming}/Programming101.md (100%) rename {projects/intro-to-programming => intro-to-programming}/README.md (100%) diff --git a/projects/intro-to-programming/Java101.md b/intro-to-programming/Java101.md similarity index 100% rename from projects/intro-to-programming/Java101.md rename to intro-to-programming/Java101.md diff --git a/projects/intro-to-programming/Java102.md b/intro-to-programming/Java102.md similarity index 100% rename from projects/intro-to-programming/Java102.md rename to intro-to-programming/Java102.md diff --git a/projects/intro-to-programming/Programming101.md b/intro-to-programming/Programming101.md similarity index 100% rename from projects/intro-to-programming/Programming101.md rename to intro-to-programming/Programming101.md diff --git a/projects/intro-to-programming/README.md b/intro-to-programming/README.md similarity index 100% rename from projects/intro-to-programming/README.md rename to intro-to-programming/README.md From 6570a8e700fdcca860a7c8f53499f2a15eeb4d2b Mon Sep 17 00:00:00 2001 From: Yxhej Date: Mon, 7 Oct 2024 11:55:11 -0400 Subject: [PATCH 2/7] add readmes --- README.md | 28 ++++++++++++++++++++++++++++ reference-sheets/README.md | 3 +++ 2 files changed, 31 insertions(+) diff --git a/README.md b/README.md index e69de29..d71e2bf 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,28 @@ +# SciGuides + +Welcome to SciGuides, a repository made by FRC Team 1155 and 2265 to gather all of our experience and knowledge for public and internal use. + +## Usage + +SciGuides is project-based, containing guides and reference sheets aimed at guiding readers towards a high level of competency around FRC code. + +It can be used as teaching material, robot code practice, or for referencing information and generational knowledge. + +This repository additionally functions as the curriculum of our school's central robotics program. + +## Contributing & Updating + +There are a few values we emphasize when writing SciGuides: + +- Don't reinvent the wheel. + - Maintaining more than necessary, or redundant information, would be a waste of time, so we heavily reference existing documentation from vendors, libraries, and WPILib. + - Minimize what must be changed from year-to-year! There is no need to restate information with existing documentation past a simple sentence or past the purposes of introduction. + +- Be concise. + - It's harder and daunting to read gigantic walls of text. + +- Experiencing is the heart of learning. + - It is our firm belief that people learn best when actually **writing** and **seeing** code (not just text) on the screen. Code examples, code examples, code examples (and the occasional image and gif, too!) + +- 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. diff --git a/reference-sheets/README.md b/reference-sheets/README.md index e69de29..70f9873 100644 --- a/reference-sheets/README.md +++ b/reference-sheets/README.md @@ -0,0 +1,3 @@ +# Document Reference Sheets + +This folder contains guides that introduce and summarize key topics (and practices) with links to official WPILib / vendor documentation for further, in-depth exploration. From 5169f7a69bd5b2644e7412b8d4b884f128ac53ab Mon Sep 17 00:00:00 2001 From: Yxhej Date: Thu, 10 Oct 2024 14:27:19 -0400 Subject: [PATCH 3/7] update readmes --- README.md | 7 ++++--- reference-sheets/README.md | 2 +- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index d71e2bf..9cda542 100644 --- a/README.md +++ b/README.md @@ -18,11 +18,12 @@ There are a few values we emphasize when writing SciGuides: - Maintaining more than necessary, or redundant information, would be a waste of time, so we heavily reference existing documentation from vendors, libraries, and WPILib. - Minimize what must be changed from year-to-year! There is no need to restate information with existing documentation past a simple sentence or past the purposes of introduction. -- Be concise. - - It's harder and daunting to read gigantic walls of text. - - Experiencing is the heart of learning. - It is our firm belief that people learn best when actually **writing** and **seeing** code (not just text) 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. + +- Keep to typical standards of documentation. + - Please look over your grammar, punctuation, and spelling before submitting your PR for review. At worst, errors should not obstruct understanding. - 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. diff --git a/reference-sheets/README.md b/reference-sheets/README.md index 70f9873..cc5f0db 100644 --- a/reference-sheets/README.md +++ b/reference-sheets/README.md @@ -1,3 +1,3 @@ # Document Reference Sheets -This folder contains guides that introduce and summarize key topics (and practices) with links to official WPILib / vendor documentation for further, in-depth exploration. +This folder contains guides that introduce and summarize key topics and practices with links to official WPILib / vendor documentation for further, in-depth exploration. From 88d6916ef2caa40aca801e0a56d2e4ba6249983c Mon Sep 17 00:00:00 2001 From: yxhej Date: Tue, 15 Oct 2024 00:42:16 -0400 Subject: [PATCH 4/7] revert project move, address review comments adding to readmes --- README.md | 12 ++++--- projects/README.md | 33 ++++++++++++++----- .../intro-to-programming}/Java101.md | 0 .../intro-to-programming}/Java102.md | 0 .../intro-to-programming}/Programming101.md | 0 .../intro-to-programming}/README.md | 0 reference-sheets/README.md | 5 ++- 7 files changed, 36 insertions(+), 14 deletions(-) rename {intro-to-programming => projects/intro-to-programming}/Java101.md (100%) rename {intro-to-programming => projects/intro-to-programming}/Java102.md (100%) rename {intro-to-programming => projects/intro-to-programming}/Programming101.md (100%) rename {intro-to-programming => projects/intro-to-programming}/README.md (100%) diff --git a/README.md b/README.md index 9cda542..8dff3e6 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,21 @@ # SciGuides -Welcome to SciGuides, a repository made by FRC Team 1155 and 2265 to gather all of our experience and knowledge for public and internal use. +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 guides and reference sheets aimed at guiding readers towards a high level of competency around FRC code. +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 as teaching material, robot code practice, or for referencing information and generational knowledge. +It can be used to teach material, practice writing robot code, reference information, or pass down generational knowledge[^1]. -This repository additionally functions as the curriculum of our school's central robotics program. +[^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 functions as the curriculum of our school's JV robotics program. ## 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. + There are a few values we emphasize when writing SciGuides: - Don't reinvent the wheel. 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/intro-to-programming/Java101.md b/projects/intro-to-programming/Java101.md similarity index 100% rename from intro-to-programming/Java101.md rename to projects/intro-to-programming/Java101.md diff --git a/intro-to-programming/Java102.md b/projects/intro-to-programming/Java102.md similarity index 100% rename from intro-to-programming/Java102.md rename to projects/intro-to-programming/Java102.md diff --git a/intro-to-programming/Programming101.md b/projects/intro-to-programming/Programming101.md similarity index 100% rename from intro-to-programming/Programming101.md rename to projects/intro-to-programming/Programming101.md diff --git a/intro-to-programming/README.md b/projects/intro-to-programming/README.md similarity index 100% rename from intro-to-programming/README.md rename to projects/intro-to-programming/README.md diff --git a/reference-sheets/README.md b/reference-sheets/README.md index cc5f0db..61a028f 100644 --- a/reference-sheets/README.md +++ b/reference-sheets/README.md @@ -1,3 +1,6 @@ # Document Reference Sheets -This folder contains guides that introduce and summarize key topics and practices with links to official WPILib / vendor documentation for further, in-depth exploration. +This folder contains guides that provide an overview of 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 From c635d303f71be0a4cb38e4eaaa395cbd90d2d441 Mon Sep 17 00:00:00 2001 From: yxhej Date: Thu, 7 Nov 2024 01:24:16 -0500 Subject: [PATCH 5/7] small prose fixes + add archive info --- README.md | 2 +- archive/README.md | 2 ++ reference-sheets/README.md | 2 +- 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 8dff3e6..ae1b525 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ It can be used to teach material, practice writing robot code, reference informa [^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 functions as the curriculum of our school's JV robotics program. +This repository also functions as the curriculum of our school's JV robotics program. ## Contributing & Updating 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/reference-sheets/README.md b/reference-sheets/README.md index 61a028f..e8b9dee 100644 --- a/reference-sheets/README.md +++ b/reference-sheets/README.md @@ -1,6 +1,6 @@ # Document Reference Sheets -This folder contains guides that provide an overview of key topics and practices on SciBorgs Programming. There are two types of docs: +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 From 2ba7c90178a71d38c740673bf93a2a2f84edecad Mon Sep 17 00:00:00 2001 From: yxhej Date: Sun, 17 Nov 2024 00:53:08 -0500 Subject: [PATCH 6/7] add conbtributing file --- Contributing.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 20 +++-------- 2 files changed, 96 insertions(+), 16 deletions(-) create mode 100644 Contributing.md diff --git a/Contributing.md b/Contributing.md new file mode 100644 index 0000000..58b45b1 --- /dev/null +++ b/Contributing.md @@ -0,0 +1,92 @@ +# 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. + +Affiliated members of 1155 and 2265 should feel free to add or modify any contents of SciGuides and its template repository as needed 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. + +Please create your own branch and pull request (PR) to make changes through the review system. + +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! There is no need to restate information with existing documentation, unless it's just a few sentences for the purposes of introduction. +- 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. + +### Writing Tips + +Avoid paragraphs of text. + +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. + +### Style + +Use [GitHub-style markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) to your advantage! + +All robot code should be formatted in single / triple code blocks with **proper indentation**. It should also be run through spotless, our code formatter. + +[comment]: # (The above might just be ridiculous) + +For GitHub & editor compability purposes, all comments should be formatted like so: +`[comment]: # (YOUR-COMMENT-HERE)` + +## TL;DR ("too long; didn't read): + +- Create a branch and pull request of your own to add features. + - Consult with leadership before +- 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 ae1b525..44df4c6 100644 --- a/README.md +++ b/README.md @@ -6,28 +6,16 @@ Welcome to SciGuides, a repository made by FRC Team 1155 to gather all of our ex 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 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. -There are a few values we emphasize when writing SciGuides: - -- Don't reinvent the wheel. - - Maintaining more than necessary, or redundant information, would be a waste of time, so we heavily reference existing documentation from vendors, libraries, and WPILib. - - Minimize what must be changed from year-to-year! There is no need to restate information with existing documentation past a simple sentence or past the purposes of introduction. - -- Experiencing is the heart of learning. - - It is our firm belief that people learn best when actually **writing** and **seeing** code (not just text) 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. - -- Keep to typical standards of documentation. - - Please look over your grammar, punctuation, and spelling before submitting your PR for review. At worst, errors should not obstruct understanding. - -- 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. +See [Contributing.md](Contributing.md) for specific directions on what we're looking for. From 41dc9a5a4434b50c76e990621c01224918586409 Mon Sep 17 00:00:00 2001 From: Yxhej Date: Tue, 19 Nov 2024 14:49:46 -0500 Subject: [PATCH 7/7] merge writing tips + style, add more tips --- Contributing.md | 50 ++++++++++++++++++++++++++++++------------------- 1 file changed, 31 insertions(+), 19 deletions(-) diff --git a/Contributing.md b/Contributing.md index 58b45b1..fd2ffc4 100644 --- a/Contributing.md +++ b/Contributing.md @@ -2,7 +2,7 @@ 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. -Affiliated members of 1155 and 2265 should feel free to add or modify any contents of SciGuides and its template repository as needed to improve the learning experience for team members and JV students. +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 @@ -10,7 +10,11 @@ If you have changes you'd like to make, discuss with a mentor or programming lea Use any editor of your choice, whether that be VSCode, Obsidian, or whatever else. -Please create your own branch and pull request (PR) to make changes through the review system. +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. @@ -24,7 +28,7 @@ We hope to maintain a quality standard for our work, so all writing should rough - 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! There is no need to restate information with existing documentation, unless it's just a few sentences for the purposes of introduction. + - 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. @@ -36,9 +40,28 @@ We hope to maintain a quality standard for our work, so all writing should rough - 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. -### Writing Tips +#### 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. -Avoid paragraphs of text. +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... @@ -70,21 +93,10 @@ I'd like to bet you chose the second selection. And that's because you can easil So, if you find yourself writing something too long (which you should avoid regardless), space it out a bit! Especially for instructions. -### Style - -Use [GitHub-style markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) to your advantage! - -All robot code should be formatted in single / triple code blocks with **proper indentation**. It should also be run through spotless, our code formatter. - -[comment]: # (The above might just be ridiculous) - -For GitHub & editor compability purposes, all comments should be formatted like so: -`[comment]: # (YOUR-COMMENT-HERE)` - -## TL;DR ("too long; didn't read): +## TL;DR (too long; didn't read): -- Create a branch and pull request of your own to add features. - - Consult with leadership before +- 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!)