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

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

[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

[Jimmy Nichols]

Originally Posted by Mark McLeod

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

I clicked the link...

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

[bdaroz]

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

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]

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

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]

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

Maybe Frank will write about this in his blag.

[Richard Wallace]

Originally Posted by Nate Laverdure

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.