Contribution Style Guide

Futureproofing and Usefulness

To make the content you write useful for teams of all resource levels, while maintaining validity in the future, the goal isn’t to go broad and shallow, but rather to go extra deep so you can equip students with the understanding of the underlying fundamentals behind concepts which they can then apply to their own unique situations. Pros and cons are context dependent while fundamentals are universal.

At the same time, things that aren’t easily accessible and/or commonly used by teams, like billet chassis and ball drive, shouldn’t be included to prevent confusion.

On the other hand, including small details that you’d only discover through actually making the thing tends to be a lifesaver for everyone (such as electrical taping cat-tongue tape to make it not peel).

Why is this important?

1. We don’t need to figure out the pros and cons of everything for students to make a decision. New products come out all the time, and equipping them with the skills lets students find creative solutions that no one would think of for their circumstances.

2. This enables students to understand WHY a team would make a certain decision and figure out tradeoffs without us explicitly telling them.

3. It makes it significantly less intensive to future proof and maintain. If the meta shifts, having to redo sections to stay competitive is time consuming. If the project dies and is no longer maintained, the information stays useful for way longer.

4. The small details are often the experience gap between the most reliable successful robots and not. It’s a lifesaver for teams without experience, and reduces the review workload on design mentors with experience.

To make this easier, here are a few tips:

1. You can usually find extremes for each concept to make it more obvious. (stealth wheels vs brass flywheels for inertia.)

2. It may be useful to find one or two meta team applications and figure out what fundamental trade offs are made for that decision. This helps learners understand how these concepts relate to each other. This also applies to mechanism examples.

3. “how to cad xyz” and IRL nuances are very useful for certain applications. Examples include sketching linkages or tensioner placement depending on load.

Inspired by gm0’s Style Guide

Don’t deal in absolutes.

• Only a Sith deals in absolutes
• Use pros/cons lists to compare options
• Explain WHY something is good or bad
  • For example, we all know deadaxle pivots are better than liveaxle. But don’t just say they’re better, say: “Deadaxles have a higher second moment of area as the torque being directly transferred to the part. As a result your pivot is significantly more robust and less prone to breaking.”
  • Similarly, we know the Kraken motors are generally good. But explain why they are good, e.g. “We would recommend using Krakens on your drivetrain because they are extremely high torque motors and will improve your acceleration. In addition, they have integrated Talon FX motor controllers that make them easier to wire and feature a high resolution encoder which will help the precision of your swerve odometry. Keep in mind that Kraken motors are not yet compatible with stock REV Maxswerve modules and require an extra adaptor from WCP to mate with other existing modules.”
• Still emphasize that teams are free to explore and innovate, but help set realistic expectations (see the following point)

FRCDesign.org is a guide from a competitive standpoint.

• Try to leave out stuff that doesn’t work well and is unpopular; if it is popular it is worth explaining the disadvantages (See tank drive vs mecanum drive; explaining tank drive, as a relatively popular and simple drivetrain makes sense, but mecanum drive, a drivetrain that no longer makes sense in the era of swerve and has little-to-no pushing power or traction.)
• Try to leave opinions out as much as possible. Do not speak authoritatively on stuff you do not have first-hand experience with whenever possible

Keep in mind that FRC design trends are temporary and transient.

• Just because something is popular one season doesn’t mean it’s the end all be all. There was a time when WCD and sheet metal superstructures was all the rage, but that doesn’t mean that we should recommend them in this guide. Try your best to think about why something is popular, and what benefits in design, function, and execution they actually bring to the table.

Social Cards

Social cards are the preview images that appear when a page is shared in Discord or other apps. They are generated automatically from each page’s title and description, so most contributors do not need to do anything special.

Mechanism example pages can also include an image in the frontmatter. This uses the same green mechanism card style as the rest of the site:

---
title: 1678's Rapid React Shooter
description: A ball shooter with rack gear actuated hood
image: ./img/1678_2022_shooter.webp
---

If a card needs different wording than the page title or description, add a small socialCard block to the page frontmatter:

---
title: Shooter Mechanisms
description: Examples and design notes for FRC shooter mechanisms
socialCard:
  title: Shooter Mechanisms
  description: Study proven FRC shooter designs and the tradeoffs behind them.
  image: ./img/1678_2022_shooter.webp
---

For tall mechanisms like elevators, use layout: mechanism-tall inside socialCard. Most mechanism pages can use the default mechanism-wide layout.

To disable a card for a page, use:

---
socialCard: false
---

Run npm run social-cards if you want to regenerate the preview images locally. The normal site build also regenerates them automatically.

Glossary Terms

Glossary terms live in src/data/glossary.ts. Add new entries there when a word, acronym, vendor abbreviation, or FRC design phrase needs a short definition across the site.

Each entry uses this format:

{
  term: "COTS",
  definition: "Commercial Off the Shelf - Parts you can buy from a vendor"
}

When you add a term:

1. Put it in the most relevant section of the glossaryTerms array, such as vendors, intake styles, parts, electronics, or design concepts.
2. Keep term to the exact spelling readers are likely to see in content. Matching is case-insensitive, so COTS will also match cots.
3. Keep definition short enough to work as a hover tooltip. One sentence is usually best.
4. Add alternate spellings as separate entries only when contributors actually use both forms, such as Poly and PC.
5. Run npm run build before opening a pull request to make sure the glossary data still compiles.

Glossary terms are automatically underlined in page text and show their definition on hover. They are matched as whole terms, so avoid adding very common short words that would create distracting highlights across unrelated pages.

The public glossary page at /resources/glossary/ is written separately in src/content/docs/resources/glossary.mdx. If a new term should appear in the visible glossary list, update that page too.

Brand Standards

Adhere to brand standards when possible.

• Abide by FIRST Trademark guidelines, available here
• The first instance of FIRST and FRC on a page should include the registered trademark symbol (i.e, FIRST®)
• Always capitalize and italicize the name FIRST
• Do NOT use a possessive on the FIRST name (e.g, FIRST’s)
• This also applies to team names: spell them how they are officially spelled
• Check The Blue Alliance if you don’t know how to spell a team’s name

You can use “you” when writing, when it makes writing less awkward. However, try avoiding excessively using it.