search

algorandfoundation / docs

MIT License
112 stars 284 forks source link

Add an Overview page to /SDKs, /REST APIs & /CLI Tools, and add index doc to each SDK folder #650

Closed fionnachan closed 2 years ago

fionnachan commented 2 years ago

Is your addition related to a problem? Please describe. Developers need a high-level overview of the Algorand toolchain and a go-to info page which provides context for understanding how to make use of the SDKs, REST APIs, and CLI tools to get information from and interact with the Algorand blockchain for their dApps and websites.

Describe the solution you'd like

  1. The current documentation folders /SDKs, /REST APIs, and /CLI Tools should be grouped under a folder, e.g. /Development Tools

  2. The Overview page should

    1. sum up the capabilities of the SDKs
      • it should state that the SDKs provide wrappers of the REST APIs for Algod, KMD, and the Indexer, and in addition to these, they provide utility methods, e.g. encoding/decoding, microalgosToAlgos, and signing methods etc.
      • general use cases of each tool (the SDK/the direct REST APIs/the CLI Tools) being the most suitable over the other tools
      • ideally it should also briefly mention alternatives for each category of methods, e.g. for js sdk, signing using wallet provider's method in the frontend vs signing with the SDK method
    2. include the full list of SDKs (both maintained by Algorand and by the community)
      • with direct links to the SDK github repos and docs

  3. Add a link to the SDK's full documentation under each SDK category on the side nav

  4. Add an index page for each SDK with links to relevant tutorials and demo github repos

Describe alternatives you've considered The following is a partial solution which should be implemented regardless:

This alternative would provide some more context than the docs currently do but it would still be hard for many developers to acquire an understanding of the toolchain without getting in touch with an experienced Algorand developer.

barnjamin commented 2 years ago

I agree, we should have a default page open on each of those with a summary of the contents. In the case of REST APIs we can probably re-purpose the restendpoints page for that

barnjamin commented 2 years ago

https://github.com/algorand/docs/pull/656 for the start of an SDK index