There has been some time, when I have not needed help. Now I needed some example and syntax of certain commands.
I went to www.arduino.cc and tried to find the language references.
The pages are now so 'artistic' that they are totally useless.
It seems that arduino is nowadays an environment to make money and not a playground for hobbists and a learning device for kids as it was.
The last bullet is that on the pages of Language Reference have tiny font, which can not be zoomed. So the pages are mostly empty space when you first find them.
The examples are weird and mostly useless. Mostly so that the word in question is not in the main role. An oneliner would be enough in most cases.
You couldn't find Documentation, then Programming?
Here is the bottom of the page you mentioned, I don't see what you are complaining about, maybe wrong site?
It's poorly indented, poorly colored (dark blue and grey on black), and awkwardly coded.
With a slight re-write to use innermost scope and the IPO model, you get the oneliner example with an explicit return type:
void setup() {
Serial.begin(9600);
}
void loop() {
unsigned long myTime = millis();
Serial.print("Time: ");
Serial.println(myTime); // prints time since program started
delay(1000); // wait a second so as not to send massive amounts of data
}
Website redesigns often push towards marketing style, with lots of white space and minimal text. On my screen, the headings are twice the size of the content, 4 times as big if you include their content-diluting line-skips.
Good reference material highlights the material the folks came to the page to find, and pushes the organizing material into the background. Personally, I prefer the Edward Tufty data-ink wise, more information dense reference material, like https://www.nongnu.org/avr-libc/user-manual/group__avr__math.html -- Along with sin(), cos() and tan(), Arduino does atan2(), but you wouldn't know it from the Arduino docs.
...And in the particular case of case of millis(), it might be good to have a second example of the non-blocking usage that millis() enables:
void setup() {
Serial.begin(9600);
}
void loop() {
unsigned long myTime = millis();
static unsigned long lastMillis = -1000; // backdate the previous timestamp
if (myTime - lastMillis >= 1000) { // wait a second so as not to send massive amounts of data
Serial.print("Time: ");
Serial.println(myTime); // prints time since program started
lastMillis = myTime;
}
}
Maybe in the See Also, it should link to micros() and others as micros()'s See Also links to millis() and others.
I was agreeing with the OP that the documentation is awkward. With the repeated iterations of site redesign aimed at marketing, it seems further and further from the technical support at the forum. I think the specific language reference used to be two clicks away from a user reading a forum post (hover over education or docs or something, click on language reference, then click on millis()) and now it is ~4-5 clicks? (Arduino.cc/Documentation/Programming/LanguageReference+ViewAll/Millis() ?) It's making the documentation worse.
Some good documentation shows multiple usage examples. For instance, from the OED on function in Computing:
With admonishments to use millis() rather than delay(), the fact that the reference page example on millis() uses delay() isn't terribly helpful. BWoD is good, but a bit confusing.
There are a couple interesting examples of using millis() for timing in 9 of the built-in examples. BWoD is one of the more complicated examples, but the heartbeat example in the ArduinoISP is nice example of rate-limiting using millis():
Maybe I'm doing a poor job of trying to think like a noob. In the specific, the more ambitious read those warnings and try to write clever workarounds. Also those same warnings are applicable to micros() and aren't included in the micros() notes and warnings:
In the general case, the Arduino language reference doc is uneven, and looks written by a committee weighted towards marketing. I think initially they tried to avoid types & return values so it looked less scarily technical, and then sort of added them back in piecewise as they discovered problems.
I'm certainly not Arduino, but I think more consistency, more input and output types, less whitespace, more meat, more examples, and more deep-linkage between related examples, functions, docs and tutorials would be better documentation.
Even though long chains of clicking between the forum and a reference page for a function gives more opportunity to accidentally add an Arduino to a shopping cart, shorter chains would be better for learning how to use Arduinos.
I had precisely the same reaction to the pinout PDF that I downloaded and printed for my board when I got started with it. The fonts are tiny, the coloring is low-contrast. There's little to no detail, unexplained notation, and ...
