[FRC Blog] Documentation: Reboot

[bdaroz]

From http://www.firstinspires.org/robotic...ntation-reboot posted Dec 1 2016

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, 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.

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]

Originally Posted by Mark McLeod

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]

Originally Posted by Mark McLeod

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]

Originally Posted by 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.

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]

Originally Posted by Jimmy Nichols

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.