"Gamifying" Documentation

[alecmuller]

Who wants to test drive our cool new robot?!
"Me! Me! Me!"

Who wants to write a improved control algorithm to help our robot perform better?!
"Me! Me! Me!"

Who wants to document our code, wiring, and CAD designs so other people can learn from the neat stuff we've done?!
*crickets*

Ars Technica covered a neat-looking new service from Stack Overflow that uses game-like incentives to encourage people to improve the state of a piece of code's documentation.

Every year the thousands of teams in FRC come up with some amazing designs, and while we all (mentors & students) learn from this process, I think we can go much further by figuring out better ways to document what we're doing.

As a mechanical person, I also appreciate GrabCAD as a documentation tool. Anyone can use it to share CAD files, and I think their revision-control system is also free to use. They also have a slightly game-like feedback system, and you can easily post both native CAD files (useful for ACTUALLY building on top of someone else's design) and STEP files (useful for importing designs from one package to another, like say Inventor to SolidWorks or vice versa). As an example, here's our 2015 robot (our only robot in recent years that was good enough to make it to world's) with both SolidWorks and STEP files. We still could have documented this far better than we did - for example with part and assembly drawings, spreadsheets for gear reduction calculations, and a full bill of materials.

What are your favorite tools for documenting your work to make it easier for you (and others) to build on top of it?

[s-neff]

This is an interesting idea!

We CAD everything, and I have been making the students do spreadsheets & (often non-toleranced...) drawings to support their work, especially whenever we're leveraging a sponsor for manufacturing support.

However, the student motivation has had a flavor of "Hey, students, this is what we're doing now", rather than "Hey, Sam, this is what we know we need to do" which I don't like relying on. It sounds to me like driving that motivation is the topic of this thread? Interested in hearing "what works" on other teams.

[alecmuller]

Originally Posted by s-neff

It sounds to me like driving that motivation is the topic of this thread? Interested in hearing "what works" on other teams.

Exactly.

For me, the motivation is to have a library of modular robot components we can draw from on the very first day of kickoff. These components (loaders, shooters, kickers, manipulators, etc) are far more useful when they're well-documented - whether you're using them as-is or customizing the design.

I think part of why people (both students & mentors) struggle to recognize the value of good documentation is that they've never really seen it, so I'm looking for examples of great documentation as well as hearing what processes other teams use.

[ASD20]

Originally Posted by s-neff

It sounds to me like driving that motivation is the topic of this thread? Interested in hearing "what works" on other teams.

Ideally the recognition of the utility and importance of documentation is motivation enough. Even forgetting the fact that a BOM is needed to compete, good documentation can increase your chances of winning engineering awards. Documentation not only makes your design seem a lot more professional, it will also likely help you with being able to talk to the judges well. It can also help raise your standing in the FRC community. Yes, part of the reason we always talk about teams like 254 and 1114 is that they build really good robots, but we also talk about them because they document their really good robots really well.

Having said that, I know it takes time to gain an appreciation of the value of documentation. After 4 years, my team is just starting to truly appreciate it. In the meantime, I would say that the best way to motivate students to document is to make it clear that it is looked highly upon when selecting team leadership. Let me be clear, this is not bribery at all because by working on documentation, students are showing many of the traits and skills needed to be a good leader. I am going to use the example of the BOM, though this also applies to other forms of documentation. I can't think of a better way to learn about every single part on the robot and what it does, than creating a spreadsheet of every single part on the robot. Writing the BOM also familiarizes you with FRC suppliers, the KOP, and the manual. It also demonstrates a lot of good leadership skills like organization, attention to detail, commitment, and being willing to do less desirable jobs for the sake of the team.

[s-neff]

Originally Posted by alecmuller

For me, the motivation is to have a library of modular robot components we can draw from on the very first day of kickoff. These components (loaders, shooters, kickers, manipulators, etc) are far more useful when they're well-documented - whether you're using them as-is or customizing the design.

I want a mechanism library. I don't know if my students want one. They seem to like Just Making Things.

Originally Posted by ASD20

Ideally the recognition of the utility and importance of documentation is motivation enough.

Ideal worlds are for physicists...

Having said that, I know it takes time to gain an appreciation of the value of documentation.

It takes experiencing the documentation being valuable, for appreciation to set in. "I didn't know what to do, until I found a solution in last year's documentation." Maybe when i'm in "teacher-mode", working in explicit references to "you know how to do this, you did it last year."?

In the meantime, I would say that the best way to motivate students to document is to make it clear that it is looked highly upon when selecting team leadership. Let me be clear, this is not bribery at all because by working on documentation, students are showing many of the traits and skills needed to be a good leader. I am going to use the example of the BOM, though this also applies to other forms of documentation. I can't think of a better way to learn about every single part on the robot and what it does, than creating a spreadsheet of every single part on the robot. Writing the BOM also familiarizes you with FRC suppliers, the KOP, and the manual. It also demonstrates a lot of good leadership skills like organization, attention to detail, commitment, and being willing to do less desirable jobs for the sake of the team.

I like this carrot. Do note this is a carrot that doesn't always work for every student. It worked on me, but I am not every student.