Every now and then I see an example with a glaring error, and often see people basing their code on these examples.
The one that triggered this post is the "Debounce" article here:- Debounce
It uses a 'long' variable, (lastDebounceTime), to store the value returned by 'millis()', and no doubt has caused countless beginners to do the same. (Of course, it should be stored in an 'unsigned long'.)
I was about to refer a beginner to this article yesterday, but had to stop when I noticed the error.
How does one go about modifying, or suggesting a modification, to examples like this?
I tried clicking on the https://www.arduino.cc/en/Tutorial/Examples?action=edit link at the top of the article, but it took me to a login page, (despite the fact that I'm already logged in), then after entering my username and password, it just opened the main Arduino home page, with no hint of how to open a page where I could make a suggestion or edit the article myself.
Are these erroneous examples set in concrete forever?
How does one go about modifying, or suggesting a modification, to examples like this?
You submit the corrections to the web master who will instantly ignore it. That is the official recommended method and it has worked on several occasions for me.
In other words forget it, there is no interest form the people running the web site to correct much. There is the howler of the decoupling cap being on the latch pin for the shift out tutorial I have been trying to get corrected since 2009.
Grumpy_Mike:
You submit the corrections to the web master who will instantly ignore it. That is the official recommended method and it has worked on several occasions for me.
In other words forget it, there is no interest form the people running the web site to correct much. There is the howler of the decoupling cap being on the latch pin for the shift out tutorial I have been trying to get corrected since 2009.
Thanks Mike. I did suspect as much, but hoped I was wrong. I guess that's why the "Edit" link leads nowhere.
Pity, it makes a lot of the examples worse than useless, teaching people the wrong way to go about things. It's a bit sad really.
And I do remember you mentioning that cap in the past. I'd sort of thought it might have been fixed by now.
That Debounce sketch is actually one of the examples included with the Arduino IDE. I'm not sure that it would actually cause any issues but certainly isn't the right type choice.
It's important to make a real effort to check to be sure the issue hasn't already been fixed or reported and to give a clear explanation. Every issue report will be looked at by multiple developers as well as the many other interested parties who follow the repository and thus receive emails for everything issue or pull request. As we well know the developers have many bugs and improvements they should be spending their time working on so the last thing we want is unnecessary distractions. In that way redirecting issue reports to the black hole of the forum does serve a purpose. Even so, beginners still frequently manage to stumble onto the tracker with their inappropriate support requests. Sadly they would usually have gotten an answer within hours if they had posted to the forum as they are supposed to. Of course, I know none of that applies to OldSteve or Grumpy_Mike but not everyone who visits this forum is quite as respectful a member of the community.
I try to transfer issues from the forum when I have hardware/knowledge/time to verify but I miss some.
I've found the best results when I provide a suggested change rather than just reporting an issue. This allows them to just cut and paste if they are in agreement. That makes their job easier and you are sure the fix will meet your approval, plus it's kind of a kick to see a couple lines of code or sentences you wrote on the website. The developers are fluent in English but it's not their first language so it's easier for me to write the documentation since it is mine.
In this case, because it's one of the included examples, you could even submit a pull request with the fix for that sketch, then they only need to click the merge button and that part of the issue is solved.
As for the edit button, I don't see one at that link but that would be a separate valid issue. It sounds like something creeping over from the Arduino Playground, which has those. I've had less luck getting that sort of thing fixed, there's a different member of the team in charge. The guy who usually fixes the documentation, agdl, is easy to work with.
pert:
As for the edit button, I don't see one at that link but that would be a separate valid issue. It sounds like something creeping over from the Arduino Playground, which has those. I've had less luck getting that sort of thing fixed, there's a different member of the team in charge. The guy who usually fixes the documentation, agdl, is easy to work with.
Thanks for the reply pert. I'm pretty tired now, been up most of the night, but later after some zzzzzs I'll follow up further and submit an issue report if it hasn't already been reported. It hasn't been fixed on the website, as you saw, but the example included with the latest IDE may have been. I'll try to find out first. (I didn't realise that example was also included with the IDE until you mentioned it.)
Regarding that "Edit" link, it's sort of hidden. Near the top of the page is "TUTORIALS>Examples?>Digital>Debounce". The "Examples" part of that line is a link to https://www.arduino.cc/en/Tutorial/Examples?action=edit, (but as mentioned, after the login page it leads straight to the Arduino home page.)
That's not the issue, though. I'll follow up on my main concern in the manner that you suggest.
Maybe Nick Gammon can a add a page to one of the stickies called:
Corrections to tutorials and code examples that you should be aware of before you proceed with your new Arduino hobby that the web site owners refuse to update.
LarryD:
Maybe Nick Gammon can a add a page to one of the stickies called:
Corrections to tutorials and code examples that you should be aware of before you proceed with your new Arduino hobby that the web site owners refuse to update.
Good question Larry, I wish I was. I have bouts of insomnia. Rather than just lay there trying to fall asleep, I just get back up again and continue whatever I was doing.
Back on the subject of errors in examples, I had originally hoped that forum moderators had the power to make changes like the one I suggested, but I guess not. It would sure make things easier though.
I'm sort of nervous about the next similar issue that I find. I won't look too hard now.
Grumpy_Mike:
The last attempt at changing this was last year, I was told this:-Which I did, enclosing the text changes and modified bit mapped drawings for the web site.
Response - F all.
Anyone wanting to know the corrections see the attached.
Pretty much makes me lose hope before I even try.
From now on, I'll pretend that I don't see all of those examples that use 'int' for pin allocations, instead of 'const int' or 'const byte'.
(Another of my pet peeves.)
I just opened an issue on GitHub for the error in the 'Debounce' example, after a search for the term 'Debounce', which turned up nothing.
I'll see what happens, but won't hold my breath.
(There are a lot more important issues for them to address, but you never know.)
I think I have come to the right conversation string. (Sorry, this is going to sound like a repeat of an ignored conversation, but I am persistent in a nice way - I hope.)
The article in the Arduino Playground on the DS3234 RTC has a couple of problems, the most serious of which is the software referenced by the author can't be downloaded.
I'd be happy to provide information and/or update the article because I have gotten the RTC to work with two different application sets in the public domain, one of which is on Github. (One works perfectly, and one has one function out of five or six that doesn't work properly, but it doesn't detract that much. I'll be investigating a fix, but don't hold your breath that I will be successful.)
This conversation thread is applicable to the Tutorial section. Should I follow the same approach for the Playground?
Thank you in advance for your advice.
Vic
(And thank you, OldSteve for help you have given me in the past. It was appreciated!)
The Arduino Playground is a different(better) situation than the Tutorials or other sections of the Arduino website because it's a publicly editable wiki. If you see any issues on the Playground please do go ahead and fix them. You can find more information on this at the Arduino Playground - Participate page.
When you go to make an edit a password page will appear. Don't worry, the user and password are prefilled. All you need to do is click the checkbox(or sometimes do a captcha) and you're in. This was added because the webmaster was concerned about spammers editing the playground.
When I find a dead link on the playground I try to fix it by doing some searching to see if the target page still exists but was just moved. If I can't find it then I check the Wayback Machine to see if a usable copy was archived. If the target page is truly gone then I remove the link.
Please don't request the Arduino developers to edit the Playground pages, they are the responsibility of the community. If you don't feel comfortable doing the edit it's fine to point out issues on the forum and hopefully a forum member will step up to fix it. I like the "Be Bold" philosophy of Wikipedia. Hopefully there are enough people like me watching the playground that community as a whole can be sure that the content continues to improve. I have subscribed to the Arduino Playground RSS feed. This gives me a notification for every edit so I can check it out and revert any vandalism or spam.
vdolcourt:
This conversation thread is applicable to the Tutorial section. Should I follow the same approach for the Playground?
My guess would be "Yes", but maybe someone else can verify. Two days ago I didn't know how to do it myself.
Edit: The real answer is "No", as I just learned.
(And thank you, OldSteve for help you have given me in the past. It was appreciated!)
OldSteve:
My guess would be "Yes", but maybe someone else can verify.
Please read my comment above. The answer is a definite "No you should not follow the same approach". We should only make requests of the developers when they are the only ones who can make those changes, as in the tutorial section. I agree that this is an appropriate thread to discuss the topic.
pert:
Please read my comment above. The answer is a definite "No you should not follow the same approach". We should only make requests of the developers when they are the only ones who can make those changes, as in the tutorial section. I agree that this is an appropriate thread to discuss the topic.
Sorry pert. Somehow I missed your previous reply until right now. (I don't think I realised there was a second page. )
I stand corrected. (And I just made a note to that effect in my last reply.)
Thanks for pointing me in the right direction, pert. It was worth the effort after all.
(I noticed that the debounce time was also changed to 'unsigned long', which wasn't necessary, but at least the variable that stores 'millis()' is now large enough to prevent problems.)
