search

multiversx / mx-docs

22 stars 142 forks source link

Elrond Documentation improvements suggestions #408

Open bogdan-rosianu opened 2 years ago

bogdan-rosianu commented 2 years ago

This issue is open so new feedback or suggestions are written in the comments.

Please write in the comments any relevant improvements suggestions. These can include lack of documentation in some areas, things that one tried to do but didn't find any documentation about, and so on.

MWFIAE commented 2 years ago

I love the erdjs cookbook, it would be great to also include sections about the additional packages like walletcore or the signing providers as well :) So stuff like how to load a pem file, how to sign with the maiar app, etc. :)

phouverneyuff commented 2 years ago

Maybe add links more walk-through videos (official or from community)

xk4r00t commented 2 years ago

A docker container with all the library needed to interact with Elrond BC (in python) + rust to build SC could be awesome to me, a ready to code in 2 minutes for new builder.

I made myself a tiny docker file (some command must be run manually), but providing something official could be nice :

FROM python:3.9

RUN apt update && apt --yes --force-yes install wget unzip build-essential python python-dev virtualenv libncurses5 sudo

RUN useradd -m elrond && echo "elrond:elrond" | chpasswd && adduser elrond sudo

RUN echo 'elrond  ALL=(ALL) NOPASSWD: ALL' >>  /etc/sudoers

USER elrond

WORKDIR '/home/elrond/'

RUN echo "alias ll='ls -lah'" >>  /home/elrond/.bashrc

RUN echo "PATH=$PATH:/home/elrond/.local/bin" >>  /home/elrond/.bashrc

RUN wget -O erdpy-up.py https://raw.githubusercontent.com/ElrondNetwork/elrond-sdk-erdpy/master/erdpy-up.py

RUN python3.9 erdpy-up.py

# Install rust
RUN curl https://sh.rustup.rs -sSf | sh
RUN echo "source $HOME/.cargo/env" >>  /home/elrond/.bashrc

# used by profiler "erdpy contract report"
RUN erdpy deps install twiggy 

CMD /bin/bash

Page to complete : https://docs.elrond.com/validators/mainnet/use-docker/

Edit : I found this container image in the official docker hub : https://hub.docker.com/r/elrondnetwork/elrond-sdk-erdpy-rust may be it already do the job but at least we could add it in the documentation as fallback for people who want to use erdpy.

SergiViP commented 2 years ago

Some suggetions:

SkyzoxRobin commented 2 years ago

In the ESDT tokens docs, there is a good explication to know how to issue, set local roles, and mint tokens via built-in functions, but there is a lack of explanation of how to do the same thing in an SC.

So it would be nice to have code snippets and explanations for :

PS: Same thing for the NFT Tokens docs.

juliancwirko commented 2 years ago

Maybe extract the 'developers' section from the docs to a separate service (ex. developers.elrond.com) where it could be better organized with a clear separation of the dapp building blocks and smart contracts building blocks. With the common ground in the form of up-to-date simple, mid, and more advanced tutorials.

It would also be nice to have a UX specialist who could design such a website. Good design would also be great because it will catch attention at the first interaction with the website.

Also, in the erdjs cookbook, there are code blocks without broader context, which can be confusing for beginners. Missing imports, some not explained assumptions, etc. Having links to the repositories from where these code blocks are copied would be perfect.

I would also love to see a very minimal example of a Rust testing framework configuration and tests, without any 'wrappers', abstractions, without Mandos generation, etc, just essential stuff on a simple smart contract, like the 'adder'. Plus some general info about Mandos <> Rust testing framework relation (what, when, why should be used). All in one section.

Keeping all up to date will be challenging but crucial. It could probably be one of the todo points in each tool version release.

newtmex commented 2 years ago

A more complete and organized documentation for testing of SCs. Maybe we have a Testing section under the Developers part of the docs where all things SC testing are explained in-depth. From setting up and updating a local-testnet (updating the nodes, proxies, etc to user specified version; testnet.toml structure and options in it to setup the configs the proxies, observers and other components of the testnet), then the rust testing framework, then the two flavours of Mandos test (go and rust)...

phouverneyuff commented 2 years ago

It would be great to have:

andrei-x1 commented 2 years ago

The big picture regarding all available APIs + their specifics. If someone doesn't know that it exists, (s)he can't use it.

In its simplest form, it could look like a table:

Almost every documentation part should firstly clearly emphasize the purpose.

Document all common impediments + common Q&As on StackOverflow:

Add examples for the trivial interesting API calls. E.g.:

bastw055 commented 2 years ago

A docker container with all the library needed to interact with Elrond BC (in python) + rust to build SC could be awesome to me, a ready to code in 2 minutes for new builder.

I made myself a tiny docker file (some command must be run manually), but providing something official could be nice :

FROM python:3.9

RUN apt update && apt --yes --force-yes install wget unzip build-essential python python-dev virtualenv libncurses5 sudo

RUN useradd -m elrond && echo "elrond:elrond" | chpasswd && adduser elrond sudo

RUN echo 'elrond  ALL=(ALL) NOPASSWD: ALL' >>  /etc/sudoers

USER elrond

WORKDIR '/home/elrond/'

RUN echo "alias ll='ls -lah'" >>  /home/elrond/.bashrc

RUN echo "PATH=$PATH:/home/elrond/.local/bin" >>  /home/elrond/.bashrc

RUN wget -O erdpy-up.py https://raw.githubusercontent.com/ElrondNetwork/elrond-sdk-erdpy/master/erdpy-up.py

RUN python3.9 erdpy-up.py

# Install rust
RUN curl https://sh.rustup.rs -sSf | sh
RUN echo "source $HOME/.cargo/env" >>  /home/elrond/.bashrc

# used by profiler "erdpy contract report"
RUN erdpy deps install twiggy 

CMD /bin/bash

Page to complete : https://docs.elrond.com/validators/mainnet/use-docker/

Edit : I found this container image in the official docker hub : https://hub.docker.com/r/elrondnetwork/elrond-sdk-erdpy-rust may be it already do the job but at least we could add it in the documentation as fallback for people who want to use erdpy.

I've tried https://hub.docker.com/r/elrondnetwork/elrond-sdk-erdpy-rust this image use an old version of erdpy

If you need I've created this image https://hub.docker.com/r/system1337/erdpy I will try to keep it up to date

bogdan-rosianu commented 2 years ago

I love the erdjs cookbook, it would be great to also include sections about the additional packages like walletcore or the signing providers as well :) So stuff like how to load a pem file, how to sign with the maiar app, etc. :)

Hi, thanks for your contribution. Examples for signing providers are already available here:

SkyzoxRobin commented 2 years ago

I would like to have documentation on meta-transactions because there is no documentation on how to implement MT in a project, the only theoretical documentation I could find is here: https://github.com/ElrondNetwork/elrond-specs/blob/main/sc-meta-transactions.md

So if you can do some documentation on how to handle relayed tx and things around that, that would be great (it can be super useful for play-to-earn and other simple games)

chainofindustry commented 2 years ago

For the beginners it will be great if the method parameters will have more detailed explanations about what they mean, how to get them and what conversions are necessary for them to be properly set. An example for what I mean: https://docs.elrond.com/tokens/nft-tokens/ I tried to make an NFT transaction and I got every single param of that transaction wrong. I explained my workflow in this twitter thread:
https://twitter.com/OvidiuArion/status/1559878078389690369?s=20&t=sbqq3-SW6evJsWmcmpPDDQ (I must admit I was frustrated with that workflow :) )

Also basic usage examples will be very nice.

I am a Unity developer and not all developers have a web development background and it is hard for them to navigate through that dapp provided as example because most of the functionality is hidded inside 3rd party libraries.

I am making this on my own for other Unity developers out there and I try to make it for dummies with usage examples https://github.com/chainofindustry/ElrondUnityDevelopmentTools/wiki/Send-NFT-Transaction

Maybe for the basic functionalities, like login, sign transactions, send tokens, send NFTs, interact with smart contracts, calling smart contracts methods, create tokens, mint nfts, multisig wallets that most developers need for their dApp some examples for dummies might help.

Thank you!

elrond-developer commented 2 years ago

Hello community,

I like Julian's suggestion of having specialized areas of focus pages dedicated to development.

I would express the following suggestions:

  1. Add the date of when the documentation was published. This will show us how old or recent the information on the documentation is. This will allow the audience to be prepared that maybe the instructions may not work as expected as things change i.e. python versions used at the time of writing vs versions used today, etc.
  2. Continuity of documentation: For example, here is a git repo that talks about Metatransactions/relayers - in the documentation its says that this is a feature that is a built-in function which is described here. however, when you navigate to the built-in functions page, there is nothing listed for Metatransactions. The git repo doesnt even have sample codes to examine and test.
  1. the Elrond project having more dapp examples. There is a lack of examples on how to create dapps. There is only the Build a dapp in 15 minutes video, but it doesnt go into detail of how the React GUI is tied to and interacting with the Elrond blockchain and its Smart Contracts.
  2. Using other methods of creating dapps rather than just sticking with React. i.e. other webpage/GUI tools being used with Elrond like HTTP, Javascript, webGL for Unity games, Unreal engine/Elrond interaction, etc.
  3. Being more open sourced with some of their tools i.e. review code for the Maiar app (so we can figure out how to make phone apps tied into Elrond), Maiar exchange (another dapp we can see how the gui is tied into the smart contracts). This recommendation I will also extend out to other Elrond projects i.e. Cantina Royale, lockedmex.exchange, etc. show off your code, help the community build, in turn the Elrond project gains more adoption.
  4. Some deeper dives on how the erdjs is used and integrated into webpages and javascript based projects/development. Again, more examples.
  5. Deeper dives on the libraries and repositories of the nodejs npm @elrondnetwork i.e. how do they work, how to break it down, what key lines/functions do or to be aware of, how do they tie into projects when importing and referencing them, etc.
  6. a better walk through of the git repo. what does each project do, what do they solve, better examples on how to use them (both end-user and developer backend), how do they (how to) integrate them into the Elrond blockchain/Smart contracts, better readme.md write ups.
  7. better tech writers whose job is to update and add new documentation when there are major updates to projects and code.
  8. Do a write up of how to fork and spin up our own Elrond based blockchains using the Elrond underlying back-end functionality while customizing it i.e. renaming the native coin, rename the blockchain, etc.
  9. Having a deep-dive in how to review the Rust Smart Contracts to find and pick out what all the Smart Contracts arguments are when sending erdpy commands when calling the Smart Contract. Its a bit difficult trying to guess what arguments to pass to the Smart Contract, what order to send them in, what format, it is expecting. Its hard because there is no way to really query the Smart Contract to see what endpoints are open, what format it is in/expecting to know what arguments to pass to it. The community is saying to just review the smart contract to figure out the endpoints but this is difficult because 1) Not all Smart Contracts are made public for us to know what arguments to pass through. 2) For a lot of us, we dont know Rust well and where to hone in and pick out all the little details to find where the arguments are located within the code. 3) the mandos scripts are in a format that is not easily convertible to erdpy command line syntax 4) the mandos scripts are outdated and some do not work and fail with errors due to file/folder missing so this makes it hard to follow when reverse engineering the snippet of codes to command.

Thank you!

elrond-developer commented 2 years ago

Some suggetions:

  • Detailed instructions installing erdpy in Mac (in Ubuntu always works well at the first try, but helping users to install in Mac always need some workarouns).
  • More explanation about the differences of Gateway and API (and more examples of using the gateway).
  • How to install an API and Elastic Search step-by-step with import-db in the observer squad. If possible, with more detail using any famous clous for the Elastic Search, like GCP, AWS or Azure.

Hello @SergiViP,

I just made a video on this. Please check on my channel and see if it helps.

https://youtu.be/bkrEcPE2Fsw

elrond-developer commented 2 years ago

It would be great to have:

  • complete guide about how to create and use a Multi-Sig Contract on Elrond
  • how to update a token to check another property when you previously checked "CAN UPGRADE". Can be done throw Elrond's wallet, or does it need a transaction created by Elrond cli?

Hello @phouverneyuff,

Please check out my videos and let me know if this was helpful towards your intrests in MSC Contracts. The first video in this series also tests "adding a boardmember" to the MSC which in a way is upgrading a smart contracts.

https://www.youtube.com/playlist?list=PLhGQKpg9cBtjy8yqrbtMqhW9t8cRk8hrd

elrond-developer commented 2 years ago

For the beginners it will be great if the method parameters will have more detailed explanations about what they mean, how to get them and what conversions are necessary for them to be properly set. An example for what I mean: https://docs.elrond.com/tokens/nft-tokens/ I tried to make an NFT transaction and I got every single param of that transaction wrong. I explained my workflow in this twitter thread: https://twitter.com/OvidiuArion/status/1559878078389690369?s=20&t=sbqq3-SW6evJsWmcmpPDDQ (I must admit I was frustrated with that workflow :) )

Also basic usage examples will be very nice.

I am a Unity developer and not all developers have a web development background and it is hard for them to navigate through that dapp provided as example because most of the functionality is hidded inside 3rd party libraries.

I am making this on my own for other Unity developers out there and I try to make it for dummies with usage examples https://github.com/chainofindustry/ElrondUnityDevelopmentTools/wiki/Send-NFT-Transaction

Maybe for the basic functionalities, like login, sign transactions, send tokens, send NFTs, interact with smart contracts, calling smart contracts methods, create tokens, mint nfts, multisig wallets that most developers need for their dApp some examples for dummies might help.

Thank you!

Hello @chainofindustry,

Please check out my channel and let me know if you find these videos helpful: https://www.youtube.com/channel/UCkYeLVHM2QmOM5uleN7D1cw

bogdan-rosianu commented 2 years ago

Hello! As an update, many of the items described in this issue were solved. You can follow the PRs activity here:

MWFIAE commented 2 years ago

Maybe a bit of documentation for the herotag/dns system would be nice :) Currently there is nothing in the docs about it.

juliancwirko commented 11 months ago

I think we need some more clarification and refresh on the 'Tokens' section.

I think the best would be to split all the types into separate sections (EGLD, Fungible ESDT, Non-fungible ESDT, Semi-fungible ESDT, Meta ESDT), even if we need to copy some content in each section. Or at least indicate that some functions are the same in each section but from within the section, not on some other page. This way, developers are sure that they have complete documentation on one topic and don't have to switch pages.

Also, some built-in functions need to be clarified—for example, burn/mint functionality for different token types. The ESDTRoleBurnForAll is not covered. It must be clarified that every owner can trigger local burn for tokens even when their address doesn't have the ESDTRoleLocalBurn for that token. It is also unclear if Meta tokens can be frozen and wiped. For now, all is a bit mixed up. We don't have a separate section for Meta tokens, and we have one section for NFTs/SFTs. For example, we have docs on burn, wiping single NFT, and adding SFT-only quantity in one page/section.