search

wpilibsuite / frc-docs

Official FRC Documentation powered by Read the Docs
https://docs.wpilib.org
Other
145 stars 258 forks source link

Correct FRC acronym branding #250

Open Kevin-OConnor opened 4 years ago

Kevin-OConnor commented 4 years ago

The registered trademark symbol should be added to the first use of the FRC acronym in body text on any page where it appears.

This can be accomplished by using

..include:: <isonum.txt> at the top of the document and the using FRC\ |reg| at the first usage of the acronym

sciencewhiz commented 4 years ago

There should be a space between .. and include: .. include:: <isonum.txt>

Daltz333 commented 3 years ago

Are there areas where this is still needed? Can someone do a grep?

AustinShalit commented 3 years ago

(Checking acronym formatting would be a great candidate for a check in CI. It could also check all of the other acronyms that we use)

Daltz333 commented 3 years ago

I think that would be best as part of a formatter. #228

jasondaming commented 3 years ago

So what all does this apply to. I see: FIRST FRC any others? (I would imagine it could (maybe should) apply to: Microsoft, NI, Axis, CTRE, Vex, etc.

jasondaming commented 3 years ago

what about the FRC Game Manual at the top of every page? I assume that needs it too?

jasondaming commented 3 years ago

does frc-docs need to have it also?

Daltz333 commented 3 years ago

frc-docs is creative commons with limitations. Additionally the acronym is only required in certain contexts.

jasondaming commented 3 years ago

Note that the ..include:: mentioned above will not work. There must be a space between .. and include

ofekashery commented 3 years ago

FRC® is the former name and it should appear as little as possible in official use. According to the FIRST Branding, it should be written out as FIRST® Robotics Competition, not FRC.

Daltz333 commented 3 years ago

That's not really feasible for us. @Kevin-OConnor can you confirm

Kevin-OConnor commented 3 years ago

Yes, we are trying to minimize use of the acronym, why is it not feasible?

Daltz333 commented 3 years ago
  1. We probably don't want translators to translate it
  2. Seems to add a lot of extra verbosity. Can we use FRC in titles? Or should we just avoid using FRC/FIRST Robotics Competition at all in titles.
jasondaming commented 3 years ago

I currently count 1514 uses of FRC in the docs. Not to mention all of the Titles and such it would legthen immensely. That counts links too so it isn't really that high...but it is a lot

Daltz333 commented 3 years ago

We can do it, but it'd be a long term thing to work toward. I think an appropriate short-term solution would be added a notice to the style guide to avoid FRC/FIRST Robotics Competition in titles, and use FIRST Robotics Competition as we go, updating references in documents that are updated. Or we could use the spell-checker to warn on updated documentation to update.

Kevin-OConnor commented 3 years ago

I agree, I am not suggesting we just Find/Replace it as that will add a ton of length. I think it is a longer term trying to rephrase things to say it less if they're being touched anyway kind of thing.

Daltz333 commented 3 years ago

I think the following will close this issue:

  1. Add a notice to the style guide to use FIRST Robotics Competition and not FRC. Do not use either in titles.
  2. Add someway (Github actions check) to flag certain spellings of words (FRC) and to use alternative. Perhaps a tool like wpiformat. A simple python script in scripts would be fine.
Kevin-OConnor commented 3 years ago

Yep, that sounds reasonable