3

Hello Stack Exchange Ethereum list members: Can someone recommend a better resource for Solidity programming documentation other than solidity.readthedocs.io?

To the Ethereum Documentation Team: The documentation located here >>> http://solidity.readthedocs.io is riddled with grammar issues, misspellings and spacing problems. It does not to give great detailed guidance and clear clean step by step or progressively complex code examples. There are extremely important keywords, reserved words and other important Solidity specific functions explanations that you use EVERYWHERE in your code examples that have been hidden under a "Miscellaneous" section heading for some strange reason. Once they are finally found, that leads to more disappointment because they have little or no definitions and examples to complement them. The grammar.txt file on your Github site seems like an extreme example of this problem. This file is an afterthought at best.

Other issues include examples like the following; a topic starts on a subject like "Mapping" with links to wiki pages that go way too much into depth on hash functions instead of just telling me how Solidity uses mapping in its code. There are way too many outside links to other websites that simply are off the mark with too detailed explanations about every conceivable configuration option, historical fact and theoretical reason why one word or subject was developed. This instead of just telling me how Solidity uses it and how I should use it to code contracts. It is not those external websites' responsibility to relate their subject matter to what I need to learn for using Solidity. It is the Solidity document's responsibility.

Next example, a topic on "Modifiers" gives maybe a few sentences on why and how to use it. Then the explanation immediately jumps into a complicated and almost non-related example. That example moves to advanced topics like Inheritance without clear, simple and detailed guidance on how and why Solidity uses modifiers. As a matter of fact, the entire documentation set for Solidity seems like a last minute thought where someone quickly grabbed some old code and just added comments to it. No, that's exactly what was done when I look at sections like "Solidity by Example". That section is almost useless as it almost solely relies on the comments in the program before even the first introduction into the specifics of Solidity coding principles and concepts.

Lastly, the main headings are not organized or labeled well and have unrelated subjects in them. As an example, why in the world is the subject if Libraries hidden underneath the Main "Contracts" header instead of under its own header? Why in the world would the subject of Functions not have its own header given the extreme importance of it in Solidity programming?

Judging by the over 14 thousand issues here alone, there is indeed a documentation problem. There are some great heroes on YouTube and other places who are giving MUCH MUCH better guidance than the supposed central location for documentation. Please, please, reach out to them and pay them some Ether to help you develop better docs OR; just post their videos on your doc site.

closed as off-topic by Ismael, eth Feb 1 '18 at 7:01

  • This question does not appear to be about Ethereum, the decentralized application platform and smart contract enabled blockchain, within the scope defined in the help center.
If this question can be reworded to fit the rules in the help center, please edit the question.

  • 1
    You can report the errors on the project github page or much better make pull request with the corrections. If you feel capable and willing to work you can make a request to the Ethereum Foundation for a grant. – Ismael Feb 1 '18 at 6:57
  • Welcome to the community! Thank you for taking the time to ask your question constructively. However it is off-topic for Stack Exchange meta.stackoverflow.com/questions/251134/… Another site where it can fit better is reddit.com/r/ethereum Lastly, as you get familiar with Solidity, the docs are open for all to submit pull requests for improvements. – eth Feb 1 '18 at 6:59
  • I'm voting to close this question as off-topic because point4 of stackoverflow.com/help/on-topic Questions asking us to recommend or find a book, tool, software library, tutorial or other off-site resource are off-topic for Stack Overflow as they tend to attract opinionated answers and spam. Instead, describe the problem and what has been done so far to solve it. Related: meta.stackoverflow.com/questions/251134/… – eth Feb 1 '18 at 7:01
  • Folks, thanks for the feedback. However, the second part of my question was really rhetorical and meant to be a LOUD statement. I didn't really expect a plausible answer because if I was the first one to point out that the docs are not good, then the dev community probably already accepts the poor condition of docs. I found a better book at amazon on the subject and I am reading it now. STILL, I recommend that the WHOLE ENTIRE official document for Solidity be removed, exploded and declared unsafe for anyone to read. Its a disaster! – lvto2000 Feb 3 '18 at 5:54
  • Ismael, thanks for the feedback and recommendation. Unfortunately a simple fix is not going to work for the current official Solidity documentation. It needs a complete and total rewrite. I am ready willing and able to help with that rewrite but we would need several of the Ethereum key engineers in the room to do so. I am sure that wont happen. Hopefully, if there are others in this thread who feel like i do, we can make enough noise for them to change. But I doubt that very seriously since they allowed the poor example of docs I see now as final. – lvto2000 Feb 3 '18 at 5:59