[FRC Blog] Documentation: Reboot

[bdaroz]

From http://www.firstinspires.org/robotics/frc/blog/2017-documentation-reboot posted Dec 1 2016

Documentation: Reboot (http://www.firstinspires.org/robotics/frc/blog/2017-documentation-reboot)
Written by Kate Pilotte, FIRST Robotics Competition Kit of Parts Manager, on behalf of a cross-functional team.


There’s a lot of stuff for an FRC team to comb through each season. There’s been a sense that, in the interest of being thorough, sometimes we’re redundant. This can be especially true as documentation evolves over years.

A group of us from Marketing, Operations, and FRC got together over the past few months to review how the Admin and Game Manuals have evolved, the content they cover, where that content may already be published, and filter content between evergreen (can be published/updated throughout the calendar year) and season specific (most appropriately posted on Kickoff Day because it’s deliberately a secret or doesn’t add any value before Kickoff).

As a result, the Admin Manual’s been… dissolved. Its content was either already (or will be) on the FIRST site, integrated in to the single 2017 Game and Season Manual (https://youtu.be/d9TpRfDdyU0?t=1s), or deemed just not that important and deleted. Evergreen content not already on the site is being added throughout the fall. In case you’re curious, there’s a more specific dispositioning list here (http://www.firstinspires.org/sites/default/files/uploads/resource_library/frc/game-and-season-info/competition-manual/2017/2017-manual-dispositioning.pdf).

The 2017 Game and Season Manual will be longer than last year’s Game Manual, but I promise it’s shorter than last year’s Game and Admin manual combined – and we hope a more concise resource.

Minor updates and edits to evergreen content will be done as routine website maintenance, and posting of new “important” content will be announced via the FRC social media channels (Twitter, Facebook) or described more deeply in this blog.

Ed: Links are as published, please don't blame me :)

[bdaroz]

I'm not sure what to think about this....

... no wait, I do. This is a *bad* idea. I think STIMS is great in comparison!

I admit, there's some redundancy in the Admin (and to a lesser extent, Game) manual. There's some things that can be pulled (like "About FIRST"), but I, in no way shape or form, want to hunt around the FIRST website... somewhere... to get information on various awards, policies and the like, that was previously in the Admin manual and had a clear update-and-announce policy (Team Updates).

Random "resources" and web pages on the FIRST site (nevermind finding them) can be changed and without notice, and frankly, it concerns me greatly.

Finally, we lose the single-point-of-authority the information in the Admin manual had. We could print it, bring it with us, and it was dated at the bottom of every page. If we needed to reference it at competition, it was there, and we knew it was current. We didn't have to "build" our own.

I really hope FIRST considers reversing this decision.

---
Opinions are my own, and may not necessarily reflect my team.

[Mark McLeod]

I am NOT clicking on the 2017 Game Manual link...

[mastachyra]

Yep, I don't like it. When the admin manual came out you knew these were the awards and rules for this year. Now we won't know for sure when they've settled on things for the upcoming year.

The Admin manual was especially helpful for a new team moderator. Having everything in one place was great. Someone took the time to figure out what was important for you to know. Now we'll have new moderators wandering around the FIRST website? That sounds like a bad idea. Any way to avoid using the FIRST website should be a priority.

[Cothron Theiss]

I am NOT clicking on the 2017 Game Manual link...

Naw, it's totally legit. Surprisingly, it's NOT a song by a man named Rick Astley.

It's far, far worse.

[Jimmy Nichols]

I am NOT clicking on the 2017 Game Manual link...

I clicked the link...:(

[ahartnet]

I sent the following into FRCTeamAdvocate@usfirst.org :

I want to start with saying that I appreciate trying to reduces the amount of places to go for official documentation. A webpage can stay current/live and you don't have to worry about people referencing old things that are out of date. It is also good to not have the same things in multiple places - having to make sure everything gets updated is not a good thing.

However, I think from a team functionality standpoint, this decision is unhelpful for the following reasons:

Put bluntly, the website stinks. It looks pretty but is very hard to functionally use. I am a tech savvy, young person that spends plenty of time using various internet forums and means of communication, and it is a hassle to navigate. The thought of depending on this confusing set up of a site to find important information about the upcoming season already scares me
The dependency of an internet connection means if the site goes down at an untimely situation, teams could be hosed.
The dependency on going to a website is going to make it tough for several teams. In PDF form, it's easy to read on a phone or pull up on a computer that doesn't have an internet connection. If instead we're relying on students data connections, they'll have to use data every time they go to look something up. We rarely have internet access during a meeting, and when we do the school seems to limit everything. I'm confident I'm not the only one in that boat.
By trying to reduce it, things are being spread out more. Having a manual available for awards acts as a one-stop shop to look up everything. If I want to have my students look up something about the Chairmans award and compare it to the Engineering Inspiration award, they'll now have to have two tabs open or go back webpages to get the appropriate link.
Mostly unrelated - the resource library is already very difficult to use. It focuses so much on the aesthetics that it ends up being bloated. It'd be great to have a compact viewing option so I can see more of the document names at once.
More than anything, I would greatly appreciate a compromise of being able to "print" everything on the awards sections into a PDF similar to the sections of the admin manual last year.


Additionally, anything you want a majority of teams to look at (bleacher rules, what to bring to an event, pit closing etiquette, etc), I highly recommend being included in the game and season manual. While many of the successful teams will know how to find it, those that have limited resources (including computers and internet) will not see it.

Thanks for your time and dedication to the program,
Andrew

[AllenGregoryIV]

I agree, this worries me as well. Not having accountability to some of these things worries me as a coach and a volunteer.

I would rather them have a permanent Admin manual that they just updated all the time instead relying on the website which has many issues.

[TDav540]

This feels like yet another disconnect between what FIRST feels about their website and the community at large think about it. I agree with everything that's been said above: while there are some benefits, the overall concerns and problems outweigh them by a significant margin.

[BigJ]

There are a lot of things (event rule-wise) being integrated into the website that my team or teams I know have had to show to event volunteers in the past, as other posters noted I am worried that the website resources will be seen as less "HQ official" (also worried about having to use the FIRST website).

[marshall]

This feels like yet another disconnect between what FIRST feels about their website and the community at large think about it. I agree with everything that's been said above: while there are some benefits, the overall concerns and problems outweigh them by a significant margin.

I wish I felt confident to make that statement. I thought for sure we'd see the fall of bag day after the survey given what popular opinion around these parts tends to be. I think the FRC site gets a lot of hate on CD but I'm curious how many teams actually find it as frustrating as some of us do. I'm not proposing another survey... quite frankly I can't handle the results mentally as 2016 has taught me that just because you've got popular opinion on you side doesn't mean that's how the world works. Seriously, Go Cubs!

[pandamonium]

This makes total sense! The website is a great and well organized resource for people who are already actively engaged in FIRST.

^^^^^^
*sarcasm*

[Jon Stratis]

I sent a rather long e-mail about this to FIRST... I think the effort was overall a good idea, but that the boundaries on what should and shouldn't be included in the manual weren't quite placed right. Some of the info that's been removed to only exist on the website makes sense - it's something that experienced teams already know and don't need to be retold again and again (like the definitions of GP and Coopertition). Other information maybe only applies to a small percentage of teams (like transportation exemption information), and those teams will seek the information out.

But other information applies to every team, and should be versioned and announced when updates happen. Like award information... Was it ever announced when the information for 2017 was available on the website? I checked through my e-mails from FIRST, and found one from 11/10 that said chairman's submissions were open and linked to the website, but going to the Chairman's section in the awards (which takes you to a page that includes all submitted awards) shows a date at the top of 11/23, and a date of 11/1/2016 under Updates... what do those dates mean? What updates were made on 11/1?

[frcguy]

I clicked the link...:(

Clicked it expecting the encrypted game manual was out... and was disappointed.

[guniv]

Something funny to note is that this post was originally listed under the Resource Library for some reason and they just moved it to the blog. Old link is dead.

[bdaroz]

Something funny to note is that this post was originally listed under the Resource Library for some reason and they just moved it to the blog. Old link is dead.

Thanks - I fixed the links in the original post.

[Siri]

I'm reminded of the pdf export function on the Q&A. If the goal is simply to provide a centralized website for the important/useful evergreen admin material rather than a central pdf, then adding a similar export function might relieve a lot of these access worries.

Still color me a skeptic, though. It's a worthy idea, but the number of people who've reached out in recent years to say "I can't find it on the website" is too worrisome for me. And these aren't CD or even deeply involved folks; I've watched the website drive people away across all kinds of associations. I'd very much rather they fix the UI first and then migrate more content to it.

[Cothron Theiss]

I'm reminded of the pdf export function on the Q&A. If the goal is simply to provide a centralized website for the important/useful evergreen admin material rather than a central pdf, then adding a similar export function might relieve a lot of these access worries.

I would be extremely interested in this. My team has no access to internet where we work, so we rely on paper copies of the manuals. I don't mind if they try and consolidate information, as long as it's easily accessible and it's easy to print off this information for use at shop or at competitions.

[Chris is me]

Luckily, nobody has any trouble navigating or finding what they need from the FIRST website, so all of this information will be just as accessible and easy to find as before.

.

.

.

But seriously, does FIRST think the website is easy enough to navigate that nobody will have trouble finding what they are looking for? What about the people who don't know exactly what they are looking for, who learn from reading the admin manual? This is going to get messy.

[Taylor]

Since the resources are "easily available" from the dashboard, and the awards sections seem to be floating near the top, they should be rather easy to find and utilize.
Of course that's for people logged in to the wobsite with knowledge of the resources area. It's not entirely intuitive. And I'm not sure how to access simply starting from the wobsite home page.

[Nate Laverdure]

Since the resources are "easily available" from the dashboard, and the awards sections seem to be floating near the top, they should be rather easy to find and utilize.
Of course that's for people logged in to the wobsite with knowledge of the resources area. It's not entirely intuitive. And I'm not sure how to access simply starting from the wobsite home page.
Maybe Frank will write about this in his blag.

[Richard Wallace]

Maybe Frank will write about this in his blag.As everyone knows, a wobsite is a place on the world wide wob, accessed by clacking on a lunk.

I've never heard tell of a blag, though. :rolleyes:

[marshall]

As everyone knows, a wobsite is a place on the world wide wob, accessed by clacking on a lunk.

I've never heard tell of a blag, though. :rolleyes:

https://xkcd.com/148/

https://www.explainxkcd.com/wiki/index.php/148:_Mispronouncing

[Richard Wallace]

https://xkcd.com/148/

https://www.explainxkcd.com/wiki/index.php/148:_Mispronouncing

I lived in St. Louis for many years. Cueball is a good friend of mine.

[Big Ideas]

I've only been involved with FRC (FIRST Robotics Competition) for 11 years so I don't know much. Someone please tell me what "evergreen" is.

I am personally old school enough that I like my rules as hard copy, complete, and up to date. I like the idea of taking blot out of rules but I don't want my ability to get a full set of rules dependent on my ability to hunt.

[ahartnet]

I've only been involved with FRC (FIRST Robotics Competition) for 11 years so I don't know much. Someone please tell me what "evergreen" is.

Thats the tame version of my first thought. Granted, they defined it the first time they used it, but then treated it as if that's a term for something that's always been around.

Sent from my SM-G930T using Tapatalk

[Mark McLeod]

Evergreen means unchanging year-to-year, always available and not game specific, like the purpose of FIRST or Consent forms or how Lost & Found is always handled.

[MARS_James]

So for those who haven't taken a look at their handy dandy chart the list of things that will be incorporated into the New Game and Season Manual are:
Admin 2.3.1 Getting answers
Admin 2.3.1.1 Q&A
Admin 4.5.1 Practice Matches
Admin 4.5.1.1 Filler Line
Admin 4.5.2.1 Qual Schedules
Admin 4.7.6 Inspection
Admin 5.1 Stop Build Day*
Admin 5.2 Bag & Tag & Robot Transport to Regional/Districts
Admin 5.3 Instructions for Bag & Tag
Admin 5.4 Robot Lock and Unlock Instructions
Admin 5.5 Robot Access Periods (for teams at Districts)
Game 1.1-6


*5.1 will also be posted on the website well beforehand.
They also call Game 5.5 Tourny Rules which is odd cause it refers to it as Tournament in 5.1 take that as you will, although I hope that we will not have it called a Tourny for this game (like how MC's were harolds in 2016) as it just seems like an unnecessary change for the worse.

Now my personal list of things that I would love to also be in this new manual even if it just lists the url to find the resource (Either to ensure that everyone reads it or so if they change it we know about it through a manual update):

Admin 4.2.1 Safety recommendations
Admin 4.5.2.3 Early Matches
Admin 4.5.3 Competition Agendas
Admin 4.7.4 Team Pits
Admin 4.7.4.1 Pit Rules
Admin 4.7.4.2 Pit Structure
Admin 4.7.4.3 Space Regulations
Admin 4.12 Bleacher Rules
Admin 6 All of the Awards Section

Some of these are common sense to be included (where to find the safety manual), others should be in the game manual anyway (4.5.2.3), others are rules that need to be read by EVERYONE on a team and the manual is the best way to do that (4.12). The awards section is because I am shocked how often I speak to teams who do not know what each award means, how many awards there are, or what gets them to championship once again putting it in the game manual makes it so hopefully someone knows these things.

Overall based on the handy dandy chart most of the stuff that they aren't going to be publishing and making "evergreen" makes sense although like I said above some of them should also be published. I understand not wanting information to be redundant but making it not redundant by putting it on the website and just saying hey it's there if you know you need to look for it is like saying "Welcome to your new job our company policies or in case something goes wrong, will not be discussed or even looked at during hiring/orientation, it's all available on our website which I am not going to give you a link to; Find it yourself!" No, that's stupid you tell them, "All our company policies and what to do in an emergency will be told to you now and if you forget here is where you find it on the company website"

[Richard Wallace]

Evergreen means unchanging year-to-year, always available and not game specific, like the purpose of FIRST or Consent forms or how Lost & Found is always handled.

I think in this context "Evergreen" also means subject to change without notice; i.e., what you click is what you get -- no need to worry about how the current wording of an Evergreen rule/policy/process might differ from an earlier version. And I think that is fine for many former parts of the Manual, especially those formerly included in the Admin section.

Of course, many other rules, especially those specific to the current game, are "Seasonal". Those rules are often the ones we expect to see changed, even improved, relative to earlier versions -- and they are the ones that I think teams and volunteers should expect to see discussed in Updates, Blog Posts, and some kind of version control in the Manual. And of course, ad nauseum, here on our favorite CD fora.

[DonRotolo]

But seriously, does FIRST think the website is easy enough to navigate that nobody will have trouble finding what they are looking for?
Yes. Yes, they do.

I am usually a staunch defender of FIRST HQ: I know these folks and see how passionate they are to do good work. But in the case of the FIRST Website: It is pretty, but just awful as far as being able to find information.

[Big Ideas]

Evergreen means unchanging year-to-year, always available and not game specific, like the purpose of FIRST or Consent forms or how Lost & Found is always handled.

Thanks Mark. I was thinking new APP or software. It didn't occur that it was a new (for me) term for a concept. SO, I learned my thing for the day. --Cheers