[FRC Blog] Document Iteration

Posted on the FRC Blog, 12/10/21: https://www.firstinspires.org/robotics/frc/blog/2021-documentation-iteration

Documentation Iteration

2021 DEC 10 | Written by Kate Pilotte, Sr. Kit of Parts Manager

Did you know that there are two game design teams in FIRST Robotics Competition?

One team works on the even-year games; the other team is… odd.

Did you know that, even though each season typically brings a new game (COVID), there’s content that applies to even and odd years?

For that stuff, which we refer to as “evergreen,” the two teams collaborate, discuss, debate, calmly advocate, actively listen, and openly consider various directions to take those topics (only a few tables flipped!) such that when we agree to adopt an evergreen standard, it remains relatively consistent from year to year – even as game-specific content is wildly and excitingly reinvented for each new game.

One of the evergreen efforts the teams tackled over the last year was to revise how information was presented in the game manual and what norms we wanted to revisit and revise. The motivations/value statements used in this effort included the following, in no particular order:

  • organize content in an intuitive way (so that regardless of how seasoned or new you are to FIRST Robotics Competition, you can navigate the document efficiently)
  • increase transparency re: content that is unlikely to change each year (so, if someone was new to FIRST, they could get a head start on studying manual content before Kickoff by focusing on that evergreen content)
  • lock-in numbering for rules that are unlikely to change each year (so that members of the community don’t need to update their brains with the new “keep it together” rule).
  • better meet the needs of the wide range of FIRST Robotics Competition community members

The four major changes that came from this effort are…

  1. The “Safety” and “Conduct” sections were dissolved, and those rules have been incorporated into the existing sections on a best-fit basis.
  2. Any rules we don’t expect to change much are marked with green rule numbers and headlines.

We cannot yell this loudly enough… this is not permission for all you seasoned FIRSTers to skip over these rules! Please, please read through the complete rule set at least once each season. We are begging you.

  1. Rules that aren’t expected to change from season to season start their respective sections (thus minimizing, if not eliminating, the chance that their rule numbers will ever change)
  2. A new numbering scheme that informs the rule’s section, subsection, and position in the subsection was adopted.

To see how we formally describe all that, here are excerpts from the 2022 Manual, Section 1.8 This Document & Its Conventions (spoiler alert, there will be game rules for robots):

The rule numbering method indicates the section, subsection, and position of the rule within that subsection. The letter indicates the section in which the rule is published.

  • G for Section 7 Game Rules: ROBOTS
  • H for Section 8 Game Rules: Humans
  • R for Section 9 ROBOT Construction Rules
  • I for Section 10 Inspection and Eligibility Rules
  • T for Section 11 Tournaments

The following digit(s) represents the subsection in which the rule can be found. The final digits indicate the rule’s position within that subsection.

Rules include colloquial language, also called headlines, in an effort to convey an abbreviated intent of the rule or ruleset. There are two versions of headline formatting. Evergreen rules, or rules which are expected to go relatively unchanged from season to season, are indicated with a leading asterisk and their rule number and headline are presented in bold green text. “Relatively unchanged” means that the overall intent and presence of the rule from season to season is constant, but game-specific terms may be updated as needed (e.g. changing Power Cells to in a rule about what COACHES may not contact during a MATCH). These rules also start their respective section, so their rule number is not expected to change from season to season.

The rule numbering format is also being applied to an updated version of the Event Rules document, to be released before Kickoff (soon!).

One more manual update we wanted to share ahead of Kickoff… for a long time, the use of the term “student” (for the purposes of drive team membership, who has to be present for robot inspection, and who can ask questions of a referee) specified someone who is “pre-college.” This language implied that all students in FIRST are destined for college, which we know isn’t and shouldn’t be true for everyone (college is great, but it’s not necessarily right or right now for everyone – there are so many great post-secondary school opportunities!). As a result, the formal definition of student is now “a person who has not completed high-school, secondary school, or the comparable level as of September 1 prior to Kickoff.” That doesn’t mean that someone who doesn’t meet this formal definition can’t be on a FIRST Robotics Competition team, or even identified as a student on the team’s roster – it just means for rules where the formal definition of student is invoked, anyone not meeting that criterion isn’t eligible for that role.

We’ll post an encrypted version of the RAPID REACT presented by The Boeing Company Game Manual the week before Kickoff so that you can have it at the ready come Kickoff Day. Stay tuned to the FIRST Robotics Competition Blog, team blasts, and/or FIRST Robotics Competition social media channels to see when that’s available.

Good luck this season, and be sure to Read the FIRST Manual!

20 Likes

I miss ::rtm::. Is there a way to use it on New CD?

2 Likes

Discourse does allow custom emoji if the mods wanted to bring back some of the Old CD smileys. Not sure if it supports GIFs, though.

Edit: By the way, is this the first time FIRST has confirmed the even and odd year GDCs?

3 Likes

So just to make sure I’m not missing something, they’re reformatting the manual to make clear which rules are “evergreen” so new students can study up on those before Kickoff. But they’re not actually releasing these evergreen rules ahead of Kickoff this year, so the change will really only help starting next year?

7 Likes

Probably the first time in this public of a forum, but it’s been known for a while now.

1 Like

Here is where I remember hearing about it: https://youtu.be/-rg_Vvh3x6w?t=1189

2 Likes

I’ve always been a fan of alternating between letters and numbers for sections, subsections, subsubsections, etc. This new system might as well be resistor color codes.

11 Likes

Not that there’s anything wrong with that.

Why, yes, I am an electrical engineer. Why do you ask?

6 Likes

Not to mention, how would I tell the difference between rule 11 in subsection 1 and rule 1 in subsection 11?

12 Likes

Presumably there won’t ever be more than 9 subsections in a single section. But I guess we’ll see once the manual comes out on kickoff.

They’ll probably evolve from decimal to hex.
and when there’s more than F subsections. we’re really in trouble.

13 Likes

“This one goes to eleven…”

4 Likes

Could get to ten sections by numbering the first one zero. Programmers love that trick.

6 Likes

Ooo, negative numbers, imaginary numbers, fractions, there’s a lot of (some might say infinite) workarounds possible here…

4 Likes

I would actually assume that the tenth section would add a digit, so it would go from R9nn to R10nn, or perhaps they would renumber the single-digit sections to add a leading zero like R09nn.

I actually like this new system better, because it allows for more insertion points. Having rule numbers like G15-A always seemed rather awkward to me, because they were clearly trying to shove a new rule into the end of a section but didn’t have number space for it.

1 Like

Honestly, it might just work better for them to stick a “.” between the section and the rule. First one to suggest in the blog comments gets the credit.

9 Likes

Personally, I’m with @Zook on alternating digits and letters. Unfortunately, looking at the 2020 rules, there were 10 subsections to the robot rules, and subsection 7 (power distribution) had 25 rules [R32…R56], so this method is already near the breaking point in English, and broken for translation into several other languages.

Curiously, subsection 8 of the 2020 ROBOT rules was the “Control, Command, & Signals System” subsection, and the example in the blog indicated that this was subsection 7, so maybe they are going to number the Overview subsection 0 as @Richard_Wallace suggested.

Maybe just insert a few of the more popular non-integers; e.g.,
image

Why?

Because cardinality is not important for this purpose. We only need ordinals here.

2 Likes

Honestly I have always felt that there should be 3 manuals in FRC. This may sound counter productive to making stuff easier but:

Admin: Any rules relating to anything that has nothing to do with the new game, we used to have this and the last time I remember it was 2016. It told you about FIRST in general, how to fill out stuff on TIMS, how the awards worked, what tools were recommended etc.

Game: Fairly straight forward here this is for playing the game and any rules that a referee is expected to enforce

Robot: This is for robot related rules that an inspector is meant to enforce.

This makes for an easy rules referencing system with a double letter followed by number system. First letter tells you which manual, second letter tells you subsection, number tells you rule number
For example you can use R.B.3 this is Robot Manual Bumper Rule 3, R.P.2 is Robot Manual Pneumatics Rule 2. G.F.4 is Game Manual Field Rule 4, G.R.2 is Game Manual Robot Rule 2.

11 Likes

0 1 φ 2 e 3 π 4 5 6 ϐ 7 8 9
Don’t forget bleem! It’s more an irreverent number than an irrational one.

1 Like