Feedback for IBC docs

[dakom]

Reading through the IBC docs, just noting some things for consideration. Not making a PR at this stage since some of this is definitely nitpicky/subjective, maybe even wrong. Happy to discuss this and decide if/how any of it should be addressed, and then close the issue out - perhaps with no changes at all.

Landing page

• "You can use the IBC protocol as a building block to create your own custom protocols on top of it" - I think this can be a much stronger marketing pitch. This page should emphasize the power of using contracts via IBC. Most people think of IBC as only ICS-20, and for good reason: developing anything beyond that, without CosmWasm, requires a ridiculously heavy burden of chain-level-code across multiple chains. Cosmwasm isn't just the best solution for developing IBC apps, it's arguably the only reasonable solution for IBC apps

• "IBC is a protocol that allows different blockchains to communicate with each other. It is a standard that defines how blockchains can send and receive messages to each other." - a bit redundant, communication means sending/receiving messages here, I think one of these sentences can be deleted

Getting Started page

• "To get started, you need to enable the stargate feature of the cosmwasm-std crate" - this is confusing... what is stargate? Why isn't this feature called "ibc"? I think explaining this a bit more is worthwhile

• There is still a "TODO" in Notes section

Basic Concepts page

• High-level, I think it should link to the IBC docs up front, and mention the need to run a relayer, then the rest of the doc can speak about only the relationship to CosmWasm. The rest of my notes will assume that is changed.

• "Port: An identifier that corresponds to a single module on a chain. One module can have multiple ports. Each contract has its own unique port." - I would de-emphasize the role of cosmos modules here... suggested change: "Port: every instantiation of an ibc-enabled contract creates a unique port, similarly to how it creates a unique address"

• "Channel: A connection between two ports on different blockchains that allows them to send packets to each other. Each port can have multiple channels." - I would de-emphasize the relationship to ports, but rather to contracts. suggested change: "Channel: to send messages between contracts on different chains, you must first create a channel over their assigned ports. Multiple channels are allowed and they can be distinguished by 'version'"

• "Relayer": delete (mention briefly up top)

• "Packet: A piece of binary data that is sent through a channel. It can time out if it is not delivered within a certain time frame." - small suggestion: "A piece of binary data that is sent through a channel from contract to contract" (i.e. to emphasize that it's not a client->chain thing like other messages)

Using Existing Protocols page

• I think this should be split into ICS-20 and Custom Contract subpages, where the intro page just explains the difference between on-chain protocols and custom contract protocols, and the custom contract walks through calling the Nois (or other) example

• I also think it should come after "Build your own protocol". Even though ICS-20 is the common case, it's easy to find, and hopefully someone will be coming to these docs because they want to build contracts that do more than ICS-20

Build Your Own Protocol page

• As mentioned above, I think this should come before the "use existing protocols" page. Not because of which is easier to grok, but rather from the perspective of "developers writing contracts", hopefully they are more interested in writing distributed apps that require custom logic, and that's why they're on the page

• I haven't fully groked the "advanced example"... skimmed through it, but cool stuff

Overall the docs as they are are fantastic, the above are just some small suggestions - nothing at all crucial!

[chipshort]

Thanks for the extensive feedback!
"Landing page" and "Getting started" points are very valid.

As for the "Basic Concepts" page: The problem is I don't want people to think that you are limited to contract-to-contract calls if you choose CosmWasm for your IBC protocol. You can absolutely do contract-to-module too.
I agree that the relayer feels a bit out of place in the list, but it is still important to understand how a relayer fits into the whole system because it is mentioned many times on the following pages. My intention for this page was mostly to be a sort of basic glossary for terms that I don't want to explain in the rest of the docs.
Maybe it makes sense to move the relayer down in the list, so that port, channel and packet are together?

"Using existing protocols" + "Build Your Own Protocol": I agree the page is a bit ICS-20 heavy, but I don't think there is enough to say about the custom contract case to warrant its own sub-page. First of all, it is very much dependent on the specific contract you want to use, so it would not be too helpful to explain how you do it with Nois, since it would look completely different for other projects and is also not really in the scope of our docs to explain some external smart contract project. Second of all, it's not really that complicated to begin with, since the contract you call does all the complex stuff.
Maybe I should just remove the reference to using IBC through another contract completely and focus on ICS-20 on that page.
As for ordering: Yes, I was always very unsure how to order these and I think you convinced me that the other way around is better.

I'll prepare a PR for this next week. Already started working on it.

[dakom]

sounds good to me! just to clarify, my intent was just to bring up points for your consideration, however you decide on any of them is 100% fine with me :)

I may have duplicated some of the points in my latest Vercel comments. Heads up @hashedone in case there's overlap