Known Documentation Errors/Deficiencies

[Travis Hoffman]

I figured I'd begin a thread for those who wish to post observed errors and confusing sections within the body of control system documentation. Let's post these all in one spot. Hopefully this will help the developer team more rapidly correct these issues.




I'll start with Chapter 5 of the control system manual on FIRST's control system page.

Taken from this post in this Chief Delphi thread:

"The Table of Contents of Chapter 5 does not jive with the actual sections of the document. There is no Section 5.1 "Introduction" as referenced in the TOC, so all the TOC references are incremented one section higher than what is actually in the document. This is a trivial fix that should be made and reposted to the FIRST Control System webpage immediately. To those working very hard on the development and support of this new system and its related documentation, let's scour the existing published material and fix these minor errors, please. Let's also dot the I's and cross the T's of future documentation before releasing it publicly, please. Please don't risk wasting teams' precious time, and please don't make your support jobs harder by adding unneeded confusion to the process."


Also, Mark McLeod outlines some additional detail on what is shown on the Driver Station LCD display and a few other useful in-progress details during the firmware upgrade procedure. Adding such descriptions/pictures to the official documentation would be beneficial. Stuff visibly happens between the picture you post in the docs and the end of the upgrade/DS reboot. This should be captured.

Finally, I've heard many complaints from end users who are told via the docs to refer to the "right"/"top"/"back"/etc. of a component without actually being shown a diagram defining what "right"/"top"/"back"/etc. meant to the original doc writer. I'd challenge FIRST to identify a small team of proofreaders to "think like an uninformed rookie" and scour the body of documentation to eliminate these nebulous descriptions in current and future releases.

[Rwood359]

In the FRC Programming Guide and Help file (Chapter varies by version), the description for Accelerometer Set Gain is not correct. It repeats the description for Gyro Set Gain.

[Ken Streeter]

The Table of Contents of Chapter 5 does not jive with the actual sections of the document. ...

The attached chapter 5 fixes the above, as well as the incorrect PC IP address in section 5.6.2

An update on the official FIRST pages will be forthcoming during normal business hours when the FIRST IT folks get back to work. (For not just Chapter 5, but all of the chapters.)

To those working very hard on the development and support of this new system and its related documentation, let's scour the existing published material and fix these minor errors, please. Let's also dot the I's and cross the T's of future documentation before releasing it publicly, please. Please don't risk wasting teams' precious time, and please don't make your support jobs harder by adding unneeded confusion to the process.

Without trying to whine, we really are doing our best with mostly volunteer staff. We're caught in a catch-22 here -- two months ago, when nothing was publicly released, there was a lot of chatter about "we don't care if the docs are still draft versions with errors, just give us what the beta teams have." Now that we've rushed release to get an early release control systems kit out to all teams to try to satisfy those concerns, there is chatter about "you should have waited until the documentation was better for releasing it..."

We realize we can't satisfy everybody all the time, but our mostly volunteer staff is doing their best. None of us have any interest in wasting anybody's time (that of the developers or the teams!)

Thanks for your ongoing patience with our efforts, as disappointing and bug-filled as they are sometimes.

[gary]

I count myself among what I would bet is the vast majority who are grateful for the release of the documentation, irrespective of a few mistakes. I think that the team of volunteers who have put in so many hours assembling this deserve all of the kudos we can collectively provide.

I do think that the stream of information from the teams is valuable, however. It's a process. After all of this info has been scrubbed by this larger number of eyes we'll have an even better product.

Keep up the good work.

[trilogy2826]

Hi Ken,
I would like to support gary's comment that the documentation team is doing a very good job. The people that are complaining are forgetting that they have been given a gift to get the control system early and that it is actually the documented responsibility for "early" teams to clarify the details so the remaining 1200 teams don't have the same issues. They need to be positive and keep focused on the kickoff release.

That being said, since you are on the pulse of things, can you please send out a post to the community to elaborate where the early teams should be posting their suggestions? Right now, there doesn't seem to be a good process and I'm afraid things will be missed. This post is a good start, but I think there can be a better process.

Following are my 2 cents, all based on the updated Chapter 5 file you just sent out:

1. I would suggest adding the link for the camera config IP addressing shown in section 5.5.1 step 2 to http://portforward.com/networking/staticip.htm. This is a good primer for setting the PC IP address and is useful for the entire chapter.
2. Chapter 5.1.1: I’ve seen a few forums that state there are issues with updating the driver station. I would suggest a troubleshooting section. In my case, I tried all the combinations I could think of and the thing that finally worked after hours of trying was reformatting the USB stick (there were no other auto-run programs on it before). I would also suggest highlighting that the file should be renamed after downloading it and that it is not case sensitive. The file should also be at least a few MB.
3. 5.6.2: should insert an additional step before the current step 9: Both the WGA and WRT security setting must be set to the same configuration for the link to work. You either need to set security settings on the WGA to the same as WRT or the WRT security needs to be disabled to match the WGA.
4. 5.6: Comment that all devices must be power cycled after wireless settings are changed or WRT and WGA do not sync.
5. Chapter 5.1.2.4 step 8 should say “Apply” instead of “Download Image”
6. 5.5.1 header says one of the user/password combinations must be configured from the table; step 12 should be updated to match that comment

Thanks and keep up the good work!

[Travis Hoffman]

Hi Ken,
I would like to support gary's comment that the documentation team is doing a very good job. The people that are complaining are forgetting that they have been given a gift to get the control system early and that it is actually the documented responsibility for "early" teams to clarify the details so the remaining 1200 teams don't have the same issues. They need to be positive and keep focused on the kickoff release.

I agree they are doing a good job; however, I believe we can ask for a higher standard when it comes to catching relatively "easy" errors such as the section misalignment in Chapter 5.

If I were a rookie team with the early kit, I know I would not want to be led down unintended confusing pathways by a doc error that could have been caught in five minutes had an extra set of eyes reviewed it before it was posted.

If no extra eyes are available and they need help proofreading documentation for basic organizational and structural errors, I'd be happy to volunteer to preview the information prior to release. I bet others would as well.

The "customers" of the early kit can be patient and tolerant, but it is not unreasonable to ask the "suppliers" of the content to simultaneously work toward improvement in the initial quality of the goods they deliver. Let's burn the candle at both ends, shall we?

That being said, since you are on the pulse of things, can you please send out a post to the community to elaborate where the early teams should be posting their suggestions? Right now, there doesn't seem to be a good process and I'm afraid things will be missed. This post is a good start, but I think there can be a better process.

Everyone is already directed to go to these forums to post questions and such. I feel a thread such as the current one we are in (or if you like, a dedicated forum on this site - perhaps a "Bug Report" forum that contains sections for hardware, software, and documentation) is all you need to give everyone a centralized location to post and review errors. Sending out an email blast instructing teams to post to this central site as opposed to 150 different CD and FIRST forums threads *would* be a good idea, though.

[Ken Streeter]

I feel a thread such as the current one we are in (or if you like, a dedicated forum on this site - perhaps a "Bug Report" forum that contains sections for hardware, software, and documentation) is all you need to give everyone a centralized location to post and review errors.

Our plan for release had been to have a SourceForge site up and running before the "early release control system kit" was shipped in order to have trackable "bug reports" which would allow bug reporting by all teams as well as tracking of fix status by both the developers and the teams. (SourceForge also provides a good way to organize code releases, tie bug reports to specific releases, and will hopefully enable the open source project to truly get rolling.) The beta site teams were supported in this way, and the bug report "tracker" capabilities seemed to work very well for this purpose. However, due to non-technical issues (i.e. licensing) the SourceForge site wasn't ready in mid-November when the kits were ready to ship. The decision was made to ship the kits anyway, even though it meant that support for the new system would be more difficult without the right tools.

We're still pressing forward with the above planned solution; it shouldn't be too much longer now! In the interim, the beta teams and developers are monitoring these forums as the official way to report problems. Having a forum specifically for bug reporting is a good idea, but we've been in the mode (and still are) of the SourceForge site being ready in "just a couple more days."

[lyncas]

Everyone is already directed to go to these forums to post questions and such. I feel a thread such as the current one we are in (or if you like, a dedicated forum on this site - perhaps a "Bug Report" forum that contains sections for hardware, software, and documentation) is all you need to give everyone a centralized location to post and review errors. Sending out an email blast instructing teams to post to this central site as opposed to 150 different CD and FIRST forums threads *would* be a good idea, though.

I agree on this "Bug Report" thread (moderated would be a good idea as well). Almost like an official Q&A so teams know that certain issues are being addressed.

Sourceforge is good idea for official releases but most teams are using the forums and have immediate email delivery options through the forums.

[Rwood359]

In order guarantee that tank mode works in the OTB test, DS Digital Input 1 must be grounded. Otherwise the floating input could be in any state. We had a PWM cable that only had the female connector. We tied white to black on the wire end and taped off the red before installing on the three posts.

[Rwood359]

Section 3 of the FRC Programming Guide say to set the PC to 192.168.0.90. This conflicts with the camera.
The Configuration Guide suggests .6.