[Documentation] Improve Documentation by Fixing Typos and Documentation Syntax

[animeshsrivastava24]

This is purely based on Documentation and Grammatical Problems.
@per1234 There are several small typos in the reference pages of various section . I have summarized them below, I was confused whether to raise this Issue or not.

1. https://www.arduino.cc/reference/en/language/variables/variable-scope--qualifiers/volatile/
   The color of the LANGUAGE Icon is Orange, please guide me whether it is a error or not.

While the variable is read, interrupts need to be disabled, so they can’t mess with the bits, while they >are read. There are several ways to do this:

LANGUAGE noInterrupts

2. https://www.arduino.cc/reference/en/language/variables/variable-scope--qualifiers/volatile/
   It should be program treat the variable

subsequent program treats the variable.

3. https://www.arduino.cc/reference/en/language/variables/utilities/progmem/
   Addition of commas.

There are small problems like this, if we look on a bigger scale we have a lot of typos on the whole which must be rectified.

[per1234]

The color of the LANGUAGE Icon is Orange, please guide me whether it is a error or not.

I agree that it would be better if the LANGUAGE tag was always colored the same. I don't know what the cause is or how to fix it and I don't consider it to be a huge problem so I'd prefer to focus on the many more important improvements we could make to the Arduino Language Reference.

It should be program treat the variable

Correct. Feel free to open a PR to fix it.

There are small problems like this, if we look on a bigger scale we have a lot of typos on the whole which must be rectified.

You're 100% correct. I have a long list of typos I have discovered while using the Arduino Language Reference. My intention was to do a comprehensive review of all the Language Reference content for typos and fix them all in a single PR but I'm currently trying to restrict my work to a maintenance role in the project.

If you find problems, feel free to submit a PR to fix them. I'm always available to review and merge pull requests.

[animeshsrivastava24]

@per1234 Sure, I'll look for typos and fix them. Also, can you please guide what should be a major thing to focus on to improve the Language Translator, except for fixing the typos. It would be useful to produce a major change in this process.

[animeshsrivastava24]

@per1234 I thought to reference this problem here :
In most of the files the mentioned functions , ( just an example) like digitalRead() , digitalWrite() lacks proper code syntax and are written in a normal fashion, simply like digitalRead() and digitalWrite() .
For example:
If we compare the files digitalWrite() and digitalRead() on arduino.cc, we find that digitalRead() present in the Notes and Warnings section is not present in a proper code syntax.
So, I am sending a PR by referencing this issue, since this Issue is based on both Fixing Typos and Documentation Syntax.

Please guide me.

[Edit .1 ] The given file: constants
Also requires a lot of code syntax addition, so I am little confused whether it is left intentionally?

[Edit. 2] I am also compiling a list of all the files which might need this correction and I will post it here.

[per1234]

Also requires a lot of code syntax addition, so I am little confused whether it is left intentionally?

I don't think it was intentional, but I don't know the mind of the original author of the text. Here's my own opinion on the topic:
#602 (comment)

[animeshsrivastava24]

Thank you so much for the reply. Sure, I'll follow the discussion mentioned by you.

[animeshsrivastava24]

@per1234 The document: begin() tells us about config argument and the values it can take:

An optional second argument configures the data, parity, and stop bits. The default is 8 data bits, no parity, one stop bit.

config: sets data, parity, and stop bits. Valid values are:

While reading, I felt that the documentation needs to specify the full forms of N, E and O present in the valid values of config. A person who may not be used to these terms may get confused.

N: No Parity
O: Odd Parity
E: Even Parity

Please guide me, should we include it in the documentation.

[per1234]

What do you think about doing it by modifying the syntax section like this?:

`SERIAL_5N1`: 5 data bits, no parity, one stop bit +
`SERIAL_6N1` +
`SERIAL_7N1` +
`SERIAL_8N1` (the default) +
`SERIAL_5N2` +
`SERIAL_6N2` +
`SERIAL_7N2` +
`SERIAL_8N2` +
`SERIAL_5E1`: even parity +
`SERIAL_6E1` +
`SERIAL_7E1` +
`SERIAL_8E1` +
`SERIAL_5E2` +
`SERIAL_6E2` +
`SERIAL_7E2` +
`SERIAL_8E2` +
`SERIAL_5O1`: odd parity +
`SERIAL_6O1` +
`SERIAL_7O1` +
`SERIAL_8O1` +
`SERIAL_5O2` +
`SERIAL_6O2` +
`SERIAL_7O2` +
`SERIAL_8O2`

[animeshsrivastava24]

Sure, I'll modify it as mentioned and send a PR.
Thanks a lot for the suggestion.

[animeshsrivastava24]

I understood how the files are being displayed and how the link works on the arduino.cc website with the help of discussion of the issue #654.

I found another problem:
The file print contains a link F() on Line 35

Image attached below:

On the website https://www.arduino.cc/en/Serial/Print , this link is not working

Image attached below:

@per1234 Please guide me.

[per1234]

On the website https://www.arduino.cc/en/Serial/Print , this link is not working

That is an outdated copy of the page left behind after the switch to this wonderful new system we use to work on the Language Reference. The real page is here:
https://www.arduino.cc/reference/en/language/functions/communication/serial/print/
and the link is working fine on that page.

The old Language Reference URLs should redirect to the new URLs, and most do, but others don't for some reason. I have reported the issue here: #481

[animeshsrivastava24]

That is an outdated copy of the page left behind after the switch to this wonderful new system we use to work on the Language Reference. The real page is here:
https://www.arduino.cc/reference/en/language/functions/communication/serial/print/
and the link is working fine on that page.

Thank you so much for helping me out by pointing to the new website.

The old Language Reference URLs should redirect to the new URLs, and most do, but others don't for some reason. I have reported the issue here: #481

Yes, I went through the issue, it helped me a lot to understand this.

I understood that the page: "Arduino Print" with the link https://www.arduino.cc/en/Serial/Print must redirect us to https://www.arduino.cc/reference/en/language/functions/communication/serial/print/.

So, does this means that whenever a user searches for, say Arduino Print, the link displayed will be the old one and it will redirect to new? Is there any way to entirely change the link to new one that is displayed on Google and other search engine result.

For more clarification, I meant to say that:

That does the link entirely needs not to be changed?

I don't have knowledge of how the entire thing works in the background, and how the old and new system is related. Please, can you help me to know about it?

I was also thinking of "Search Engine Optimisation (SEO) " techniques, in case both new and old system is available on the web, to make new pages appear first on the result.

I guess I will need your help to understand what happens in the background. I am a little curious.

[per1234]

I don't know anything about SEO. It's a very complex subject. One thing to consider is that there are probably links all over the Internet to the old Language Reference URLs, so we need to be sure the old URLs continue to work. However, we also don't want the people following the old URLs to get the old content that has not benefited from all the work we've done to improve the documentation over the years.

Neither of us have any access to the systems that would need to be changed to make sure the old URLs go to the new documentation (and I wouldn't know what to do even if I did have access), so we'll leave solving this issue in the capable hands of the members of the Arduino team who specialize in these things.

[animeshsrivastava24]

One thing to consider is that there are probably links all over the Internet to the old Language Reference URLs, so we need to be sure the old URLs continue to work. However, we also don't want the people following the old URLs to get the old content that has not benefited from all the work we've done to improve the documentation over the years.

Yes, I completely agree with you so does this means that redirecting the links is the only solution left?

Neither of us have any access to the systems that would need to be changed to make sure the old URLs go to the new documentation (and I wouldn't know what to do even if I did have access), so we'll leave solving this issue in the capable hands of the members of the Arduino team who specialize in these things.

Thanks a lot for the information.

[SeppPenner]

@animeshsrivastava24 @per1234 I guess, you can close this issue now? I mean, @animeshsrivastava24 If there are some new issues with typos etc, you can add a new issue? I just want to keep this a bit more clear here. (And sorry that I didn't participate in the last time but I was a bit busy...)