solang icon indicating copy to clipboard operation
solang copied to clipboard

Docs: Inconsistent usage of `Solidity` and related terms

Open xermicus opened this issue 2 years ago • 0 comments

We are not very consistent about how we use Solidity in our docs. We just use Solidity, sometimes Solang Solidity, Solidity on Solana, Ethereum Solidity etc...

This leads to discussions and unclear situations as to when what term should be used. We should define terms for each dialect, including what's used on EVM, and then overhaul the docs to achieve some consistency.

Additionally the following was noted regarding linking to other external documentation:

- Neither the `solc` compiler nor the `docs.soliditylang.org` resemble a language spec.
- Hence it's questionable whether this is authoritative because it's merely the predominant dialect or version of Solidity at the time of writing.
- Add to that, seeing the compiler or docs of a version of Solidity that can only run on a specific runtime as authority is definitively not what we want.
- From that follows, saying just `Solidity` while linking to some specific documentation or implementation should be avoided. Because it implies that the documentation or implementation linked to to be an authoritative source while it is not.

xermicus avatar Aug 08 '23 14:08 xermicus