User documentation is hard. YAGSL

Technical Programming
1

As many of you may know by now I am working on a general swerve library (YAGSL). I have been keeping in what I consider to be good development practices for the most part (sorry no unit tests). Every class, attribute, method, and package are documented with a short description of what they do and the javadoc site is public and updated nightly alongside everything else. I also maintain a updated reference guide as a github wiki. We made a simple configurator too for those who are overwhelmed by the options. Ontop of all of this we have functional example code (albeit designed to test swerve drive and not control it during matches) available too.

I know all of this isn’t enough and realize I need to make more robust indepth “here’s how to use this in a program and what you can do” guide. My problem is deciding on a medium, how to start, what should be inside of it, what should I expect the user to know about swerve drives, etc. I would rather not do a video because I am not that good at editing or writing scripts. I love how some teams are not detered by the abysmal state of user documentation but my goal with YAGSL is to make swerve plug and play for the most part, maybe even have a repository of known working configurations for most COTS swerve drives.

I am thinking of starting a readthedocs.io with all feedback and resources necessary to use YAGSL and probably learn about swerve drives.

For those of you who are considering using or already using YAGSL I would love to know what you need to learn first or wish you had learned and what format!

5 Likes
2

I may let you know how this goes in a year, my team is looking at making our first swerve drive chassis next summer for an offseason project. Thanks for collecting these resources together!

1 Like
3

Everything you mentioned would be phenomenal. In particular, hosting a repository of specific configuration examples (for different hardware), implemented in the command framework would be extremely helpful in getting teams up the steep learning curve for swerve. ie MAXSwerve or SwerveX or SDS with NavX, or Pidgeon etc.

On a side note, I think what you are doing is going to be transformational for the FRC community. Keep up the great work!

1 Like
4

If there is one thing that teams / student loves, it’s watching a video (videos suck in FRC because of how fast that things change but this should be relatively consistent). A Zero To Swerve series would be pretty cool.

1 Like
5

I have began implementing this but without example code (feel free to submit a PR with some!) in this repository.

1 Like
6

Strongly endorse a readthedocs.io page, as you’ve mentioned. Maybe take a look at the RemoteLiteralInclude Sphinx plugin to handle inlining code examples in docs (this is what we do in frc-docs).

7

Or if you wanna be a guinea pig, you could try out GitBooks. I’d be interested to see how it works out for coding docs.

3 Likes
8

I like Markdown alot so this will probably be my route. Still have no idea how to break it down and don’t have the source material (photos) to explain it efficiently.