Summary of the future organisation of SDK docs

[gamarin2]

As per discussion with @ebuchman.

• SDK book: Similar to RustBook, this is a series of tutorial that introduces the different concepts of the SDK. The SDK book is the recommended way to learn about the SDK. Currently lives here: https://github.com/cosmos/cosmos-sdk/tree/develop/docs
• SDK API spec: Godoc provides a detailed reference spec for all the functions of the SDK. Lives here: https://godoc.org/github.com/cosmos/cosmos-sdk
• SDK by examples: Self-sufficient SDK app examples.
• SDK reference doc: Detailed documentation of everything that a SDK dev might want to know. Includes detailed explanation about multistore, IAVL tree, queries, LCD, testnets, RPCs, ... This is needed in 6 months (medium term). Until then Cosmos Hub spec will be used in replacement.
• Cosmos Hub Spec: Detailed specification of all state and transitions in the Cosmos Hub state machine

[rigelrozanski]

Should we move this from an issue into some kind of "future-plans" section of the readme in docs?

[gamarin2]

Docs readme is in flux, so leaving this issue open for now

[rigelrozanski]

okay - should be more stable soon then we should merge in

[fedekunze]

@gamarin2 (cc: @jackzampolin, @zramsay, @ebuchman, @greg-szabo, @alexanderbez, @alessio ) I would change:

• SDK API spec ––> SDK GoDoc with descriptions of pkgs (ToDo)
• SDK reference doc ––> SDK Glossary
  and add
• SDK Gaia-lite API: Summary of all Gaia-lite endpoints with their ICS standards, parameters, return values, etc. Preferably in a Swagger file and hosted on the website docs

[gamarin2]

I feel SDK Glossary does not accurately reflect the content. The Reference Doc is more than just a glossary.

[alessio]

SDK API spec ––> SDK GoDoc with descriptions of pkgs (ToDo)

I very much agree to that - the lack of package-specific docs tends to make life quite tough for a new starter :)

[fedekunze]

👍@gamarin2 let's stick with SDK Reference then. Can it be Guide instead of Doc ?

[fedekunze]

I'll open separate issues to track what's needed for each of them. cc: @gamarin2 @jackzampolin

[zramsay]

obsolete / replaced by what we just did