Software for non-software team members

This is an email Tyler sent in response to a verbal request for feedback on formal varsity letter requirements. It is being preserved here for posterity.

Hi Grace,

Since you mentioned on Tuesday that the team was putting together more formal varsity letter requirements, you may be interested in the requirements the software team has been using for the last 2+ years. They are linked on https://frc3512.github.io/admin/. This email was originally intended just to mention that, but the fact that varsity letter requirements are even an issue implies there are more systemic issues. The rest of this email elaborates on what I mean and how I feel these issues should be addressed.

Varsity letter requirements

I'm hoping the software team's varsity letter requirements can be incorporated into the team-wide requirements in some way. Having every subteam document what constitutes a varsity letter in terms of specific hard and soft skills as the software team has done would not only give new students an idea of what to expect as a member of each subteam, but would also help leadership develop an appreciation for the work each subteam does. This would address frequent complaints of varsity letter recommendations being overruled, only to have them reversed when the subteam in question challenges it.

Basic knowledge

As an example of what I mean by appreciation of each subteam's work, the leadership (at minimum) should be able to understand at a basic level what each subteam mentions at opening and closing meetings. At least with software, this requirement hasn't been met. When we mention our problems and plans for addressing them, one of two things happens: 1) we explain things in sufficient detail and everyone just nods, and says "oh, more big words from the software people"; 2) we explain things with hopelessly vague descriptions because we have to strip out all our descriptive terminology, then we get yelled at for being too vague. I find both of these responses disrespectful because the majority of the things we mention are basic software concepts that all our rookies learn within their first year. I'm not saying everyone needs to be an expert on every subteam, but they should at least know the basics of what each subteam is capable of and how they work. I want to avoid subteams ignoring each other's needs as well as subteams attempting to compensate for this with well-meaning gestures but useless gestures that are a result of their ignorance. The mechanical team generally knows you need a router and CAN wires going from the roboRIO to the power distribution panel and that motors require electricity across their leads to run. Why can't the same high-level basic understanding be afforded to software or business? An analog for this exists in the corporate world, by the way: technical managers. They know how to manage a team, but aren't clueless about the tasks they hand out to their subordinates. This means they know how much work something will realistically take, be able to determine if a subordinate is slacking off, and be able to plan more effectively for the future.

What leadership should know about the software team

On the software team, we've seen that if all our members know what needs to be done, the role of a lead becomes redundant because they can coordinate tasks amongst themselves. Being able to function without direct oversight from a lead and work toward a common vision has made us really effective over the years. However, a prerequisite to this is visibility into how the subteam works at all. Pursuant to this, I would expect non-software leadership to know the following about the software team:

  1. We have standard operating procedures and our own set of goals. They are detailed in https://frc3512.github.io/admin/goals/.
  2. Software is not magic that makes the robot move. Robots follow simple instructions and basic logic, and you can write them yourself in English (If this condition is true, then do that thing. Drive for 5 meters, then turn right, etc.).
  3. There are important factors involved in making a mechanism controllable by software. See 971's video on it.
  4. Sensors are not magic, and the average electrical student should understand what kinds of sensors there are and what kinds of robot motion they can measure.
  5. We use version control. Each robot's code is stored in a "repository". We work on features separately in what's called a "branch", which are eventually merged into the "main" branch that always contains working code. We do this at competition too.
  6. We do code review for quality assurance. The site we use is https://github.com/frc3512, which lets us leave comments on code and push fixes to feature branches based on that review. We always push what we've worked on to that server at the end of each day, so no one programmer is required to be at a build session on any given day to continue another's work.
  7. If anyone wants to see the robot code's progress, they can do so by viewing the relevant repository at https://github.com/frc3512.
  8. All our curriculum is online: https://frc3512.github.io/ci/. Everything the software team learns on a yearly basis is documented there somewhere. This is how we've managed to do consistently well with just one local mentor and one mentor that's typically hours away. The rest of the team should consider documenting what they know somewhere so that knowledge isn't lost every time a student graduates.
  9. The software team is not an IT department. When the Driver Station stops connecting to the robot, we're just as clueless as you are. We usually just press power buttons at random and reboot things until it works. In fact, your average "IT expert" is basically just following the steps in this webcomic: https://xkcd.com/627/. As one of these supposed "IT experts", I can confirm this is exactly what we do.

Hopefully this long-winded email helps explain some things.

- Tyler