search

platformio / platformio-docs

PlatformIO Documentation
https://docs.platformio.org
Apache License 2.0
247 stars 325 forks source link

Various clarifications and readability improvements #101

Closed sparvanders closed 4 years ago

sparvanders commented 4 years ago

I'm new to PlatformIO so it's very obvious to me when something in the documentation is unclear. I used this as an opportunity to clarify the documentation. Since I don't know the actual code, please review each change I propose and correct if I I got anything wrong.

Here are some main categories of my changes:

Clearer and more fleshed out introduction of terms (such as what's a "platform", what's a "package" etc).

Changed vague directions like "you should use" to the clearer "you must use" or simply "use". When something is not a requirement, the words "optionally" or "may" are better make that fact clear.

Changed some formulations to improve readability; for example changing from:

"See below available directory ***_dir options." to "See the available directory ***_dir options below."

Other minor language details such as changing "a default value is" to "the default value is" as there is ever only one default value. I added a fair number of "the" to make the language flow more naturally.

ivankravets commented 4 years ago

Wow!!! The huge contribution to our docs! Thank you so much! 😊

P.S: Could you help us to improve PlatformIO IDE for VSCode? I saw you did updates to its page in docs. See https://github.com/platformio/platformio-vscode-ide/blob/develop/package.json#L505:L582 The texts are in "description" fields.

So, we could look more professionally from a grammar point of view.

sparvanders commented 4 years ago

Glad you appreciate it. Ok I'll update the vscode descriptions too. (now posted from the correct account)