Cosmos-sdk: docs: make them a better guide using example apps

[ebuchman]

Did some docs refactor in https://github.com/cosmos/cosmos-sdk/pull/1289

Introduced a new table of contents: https://github.com/cosmos/cosmos-sdk/tree/develop/docs/

The Core section should use real example apps to actually demonstrate how everything works, with the goal being to build towards full blown basecoin (or gaia).

As suggested in https://github.com/cosmos/cosmos-sdk/pull/1289#issuecomment-398167645 this can be done in 5 iterations:

• App1: just messages, handlers, baseapp, store (no accounts, tx, amino, keeper, etc.)
  
  
  
  • Msgs: Just MsgSend with From, To, Amount
  
  
  • JSON encoding
  
  
  • Account just has coins.
  
  
  • One store
  
  
• App2: Introduce Amino
  
  
  
  • Add MsgIssue, using a new store to hold the identity of the issuer
  
  
• App3: Accounts and Transactions
  
  
  
  • Introduce authentication via StdTx and an AnteHandler
  
  
• App4: Keepers
  
  
  
  • AccountMapper and CoinsKeeper
  
  
• App5: Advanced
  
  
  
  • Simple staking module
  
  

[gamarin2]

Here is how I see things @ebuchman.

I think we need two things:

• A canonical, "reference" documentation of the SDK. It should contain every feature and explain everything in an "objective" and neutral manner. I think producing this doc is the job of the core SDK team.
• Tutorials that take the reader by the hand and present things in a user-friendly way. Of course, these tutorials will often reference the canonical doc.

Because we don't have the former, I had to put more info in the app tutorial for it to be self-sufficient. Ideally, we would have the canonical doc and I could offload lots of information to it.

So to summarize I agree with the approach you mentioned in the app tuto PR: "Then this tutorial, and others like it, have a common foundation of docs to build on, and can focus on the meat of the example". I think this "common foundation" should be a formal, canonical documentation of the SDK that we don't have at the moment. This is the reason why I had to expand on the app tutorial.

Finally, I'm not sure the material in the tuto would fit the core SDK doc (except maybe the intro and jae's coderun). I have explained things not formally but in a way that is easy to understand. This is far from formal/canonical. I would be happy to trim the tuto later once we do have a more formal core sdk doc.

[jbibla]

A canonical, "reference" documentation of the SDK.

this is well under way!

Finally, I'm not sure the material in the tuto would fit the core SDK doc

should it go in the academy then? perhaps a blog post too?

[gamarin2]

should it go in the academy then? perhaps a blog post too?

I answered in the app PR. I think it should go in our docs. It's good to have at least one user-friendly tutorial there to complement the formal docs. And a blog post will accompany the release of the tuto.

[ebuchman]

Closing for #1445 and #1460