### The problem
I've had an encounter with the steem blockchain [API](https://developers.steem.io/) 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](https://stripe.com/docs/api). 
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.
![Screenshot_1.png](https://res.cloudinary.com/hpiynhbhq/image/upload/v1515692836/tbc4wojl6veqiupi2s5z.png)

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
![Screenshot_3.png](https://res.cloudinary.com/hpiynhbhq/image/upload/v1515694246/slogsycgaw2o1qysqkhz.png)
After
![Screenshot_4.png](https://res.cloudinary.com/hpiynhbhq/image/upload/v1515695021/fkmt5dptee5iorgoj8mi.png)
<sub>\* This is an example, I have no idea if the information about *setPendingTransactionCallback*  in the picture is correct</sub>
<sub>\* The design and layout might change</sub>

<sub>\* At this point of writing this post the image upload gave up... If the images bellow do not load I'm sorry...</sub>
##### The menu should have subsections
Stripe:
![stripe-example.png](https://image.ibb.co/jHHT1m/Screenshot_5.png)

Steem:
![steem-example.png](https://image.ibb.co/dSzxu6/Screenshot_6.png)

##### The community part should be enriched
Add more links to other useful projects:
- TypeScript SDK [dsteem](https://github.com/jnordberg/dsteem)
- [Steem.NET](https://github.com/VIM-Arcange/Steem.NET)
...

##### 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](https://stripe.com/docs/api) has it with tabs for each SDK.
![python.png](https://image.ibb.co/c6yqE6/Screenshot_51.png)

##### 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](https://steemit.com/steem/@vgichar/complaint-my-personal-experience-with-steem-api-it-s-a-mess) 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](https://joshdata.wordpress.com/2014/02/10/what-makes-a-good-api/)
    

<br /><hr/><em>Posted on <a href="https://utopian.io/utopian-io/@vgichar/updating-the-steem-documentation">Utopian.io -  Rewarding Open Source Contributors</a></em><hr/>