Image by @cass
The importance of a well documented API is enormous and ultimately can make it a pleasure to develop or integrate with. As new developers or 3rd party services start looking to integrate with steemit, there should be a simple developer docs accessible directly on our site.
Our API documentation should be easily found, delightful, organized, and have lots of examples.
We have a great deal of eager developer and 3rd party services who are accustomed to robust documentation which can be generally accessed directly on the main destination
Not by scouring or filtering a bunch of posts to find the solutions. It's time we up our API documentation!
Steemit Developer Collective Docs have arrived!
Logo design by @cass
Steemit Developer Docs
The new steemit developer docs, now live, can be viewed at: https://steemit.github.io/steemit-docs/Ideally we'll add this directly in our menu for new developers. Also having a direct link from our domain would be ideal http://developers.steemit.com or http://steemit.com/docs for examples(Github pages supports custom domains)
The open source repository can be viewed at: https://github.com/steemit/steemit-docs
Coverage of existing API functionality on the developer docs is currently limited but growing! *Currently, only steem developers can commit. If your a developer and would like to help contribute please contact me!
Preview
To get started, I've modified and themed slate's default UI/Styling to match the elegant and simplicity we currently have on steemit.com. The hope is the developer collective will become our official API documentation for developers and 3rd party services easily accessible in our menu. Aesthetically, it needs balance to fit well with our main site and carry over.
Together, Lets Create Delightful Documentation
Examples - For any endpoints and RPC commands it's good we give examples of expected output along with optional and require parameters. Nothing is more upsetting tapping into a 3rd party API and having to guess what optoins the payload is expecting.
Formatting - Easy to ingest, locate commands and data points. The steemit developer docs already have a search engine integrated which makes it pleasant to find resources.
Tookit/Libraries/Wrappers - We already have an incredible amount of libraries and wrappers, @fabien has amazing progress on SteemJS, @xeroc has built the great python command line tool piston, just to name a few. Let's categorize all our current and future libraries, wrappers, and components into a robust toolbox center for everyone!
Quick Hightlights
- We're utilizing the Slate API Documentation framework. Slate is a light, elegant and mobile friendly interface for building robust API documentation. It's utilized to build API documentation by companies including Mozilla, Dwolla, Clearbit, and NASA. We're in good company!
Slate is just Markdown. Developers can help contribute using a simple and light syntax we're all familiar with.
Hosting is extremely trivial and no added cost for us :) Were all hosted and already live on Github Pages!
Recap
With the Developer Collective Docs in place, we are primed to grow and collectively curate delightful and comprehensive API documentation for anyone looking to develop on steem. Let's aim to set the highest standard we can. It's exciting to take one step forward today for that vision!