The problem
I've had an encounter with the steem blockchain API a while ago and it was not so pleasant. There are several problems with the documentation:
- No request and response examples for JavaScript documentation
- No description for RPC calls for JavaScript documentation
- The menu should have subsections
- The community part should be enriched
- The python documentation is on a totally different site
- It's not intuitive to read
Proposal
One of the best documentations out there is the one of stripe.
Here we can clearly see an API call (in Java) description on the left and example request and response on the right. The request part contains both the argument object and the actual SDK invocation.
The left side clearly describes what the API call does and also provides description for each argument (or property of an argument).
Concrete parts that need to change
JavaScript RPC description (first 2 points)
Before
After
* This is an example, I have no idea if the information about setPendingTransactionCallback in the picture is correct
* The design and layout might change
* At this point of writing this post the image upload gave up... If the images bellow do not load I'm sorry...
The menu should have subsections
Stripe:
Steem:
The community part should be enriched
Add more links to other useful projects:
The python documentation is on a totally different site
If the python SDK is the same as the one for JavaScript then they should be merged with either 2 separate sections (as it is now, but with full documentation) or as stripe has it with tabs for each SDK.
It's not intuitive to read
There are examples all over the documentation just for few calls. These parts should be removed and instead there should be an example for every call as stated before.
Side effects, benefits and personal notes
Bad documentation can make the development much slower and frustrating. As I said at the beginning of this post I've used the API and out of frustration I wrote a half-story about concrete problems that I encountered. (don't upvote, resteem... just read)
The benefits are obvious, happier developers make better products. In this case Steem products.
I've forked the documentation and I'm willing to do the work myself, but will start at the beginning of February (not a promise). If there is anyone willing to do it sooner, then best regards :)
"Documentation. This is incredibly important. An API without documentation is useless. Totally useless. Because no one will know how to use it. Documentation should cover why the dataset is important, what the data fields mean, how to use the API, and examples examples examples." - Joshua Tauberer
Posted on Utopian.io - Rewarding Open Source Contributors
Thank you for the contribution. It has been approved.
You can contact us on Discord.
[utopian-moderator]
Sorry, it's my first time contributing, so I didn't know how strict the rules are about the templates... will do better next time
Hey @vgichar I am @utopian-io. I have just upvoted you!
Achievements
Suggestions
Get Noticed!
Community-Driven Witness!
I am the first and only Steem Community-Driven Witness. Participate on Discord. Lets GROW TOGETHER!
Up-vote this comment to grow my power and help Open Source contributions like this one. Want to chat? Join me on Discord https://discord.gg/Pc8HG9x