Design overall structure

[ethanfrey]

Take a look at some other docs pages for inspiration:

• https://docs.openzeppelin.com/openzeppelin/
• https://ethereum.org/en/developers/#getting-started
• https://docs.cosmos.network/#
• Produce a general structure for organizing info
• List top items that need to be added (as new issues)

[orkunkl]

I looked through some of the docs out there.

OpenZeppelin

structure:

• Learn
  • Overview
  • Setting up node project etc
• Tooling
  • Contracts
    • ERC20/70 etc
  • Testing
  • CLI

Cosmos sdk docs

• Intro
• Basics
• IBC
• Modules

Ethereum

Ethereum docs are scattered. There is solidity, homestead, node docs and more. I would say we should not take reference from there.

CosmWasm docs overview

I propose the structure below. Mixed open zeppelin for good docs and cosmos sdk for ecosystem consistency.

Introduction

• Introduction
  • What is CosmWasm?
    • Introduce of cosmwasm and documentation. We can add more sections if needed

Architecture

• Architecture(rename of intro also I think some of the docs under Getting Started will be moved to Architecture as well since they provide general info not hands on tutorial)
  • Multi-chain
  • Actor models....

Learn

Sections below is not the end product. I will modify, add or remove sections when I am going through full documentation. But sections below will give a good overview. Since it is a new category like resources, a topic can contain several docs. For example smart contracts section can contain rust basics, wasm runtime etc

• Learn (this is a separate section like Resources. It will contain an walkthrough tutorial starting from installation, writing a smart contract to deployment with a concrete smart contract, possibly name service?)
  • Installation
  • Smart contracts
  • Producing blocks(how to setup and run node)
  • Deploying to a network
  • Production Tooling
  • CLI

Plus Contracts

This section will contain documention of cosmwasm-plus

• Plus Contracts
  • CW20-base
  • CW77
  • etc...

IBC

I think IBC deserves its own section. We can give details here

• IBC

Testnets

Same of what we have at the moment.

[orkunkl]

Its the first iteration of the docs structure. Waiting for your recommendations @ethanfrey

[ethanfrey]

this is a separate section like Resources

Where is resources? I assume you editted this out?

[ethanfrey]

In general, makes sense. Can you edit and refine a bit more.

Also there are two targets for learn - the simple escrow edit that I did, and the "still to be done" namespace contract (to mirror the cosmos-sdk). Maybe we would want both - so, how to organize that? (Note the cosmos-sdk links to a separate site for these tutorials: https://tutorials.cosmos.network/)

Especially as we will have hands-on sections (tutorials and using the cosmwasm-plus contracts) we probably want to consider how to place these hands-on sections with the theory. Ideally not two different sites like cosmos. (But I do like cosmos's landing page)

[orkunkl]

this is a separate section like Resources

Where is resources? I assume you editted this out?

[orkunkl]

Also there are two targets for learn - the simple escrow edit that I did, and the "still to be done" namespace contract (to mirror the cosmos-sdk). Maybe we would want both - so, how to organize that?

Escrow tutorial gives detail about the code but not the step-by-step development flow like State -> Msgs -> Handlers - > etc
I see two options:

1. Base nameservice on escrow tutorial and have a single document.
2. Have 2 separate tutorial docs: step-by-step tutorial (nameservice), fast and short overview of cosmwasm smart contract document(editing escrow) in overview section for taking a quick look at the smart contract system.

[ethanfrey]

Ah.. yeah, we should definitely link the new faq site from resources

[ethanfrey]

Escrow should be a simple "edit this contract with a few dozen lines or code" starter.

Nameservice is a "build a contract from scratch".

More like escrow first for people who don't know rust. Once you got the basics or already know rust, go for nameservice

(Option 2 above)

[willclarktech]

Re the intro section: it's also quite difficult to engage with large parts of it if you don't know what it's talking about (e.g. if you haven't done the tutorial). I'd recommend trimming down the intro to the bare bones, shove people into the tutorial, and then put the details in a "deep dive" section that's later in the sequence.

I realise the overview suggests jumping straight to the tutorial and coming back to the intro, but why are we recommending a different order to the one we've chosen ourselves? And why is this called the "intro" if we're suggesting people do something else first?

Also there are quite a few asides or references to concepts without a lot of explanation, e.g.:

The same contract should run on two distinct blockchains, with differing Golang modules, different versions of the Cosmos SDK, or ideally, even based on different frameworks (eg. running on Substrate). This should be possible when avoiding Custom messages, and checking the optional features one uses. The features are currently staking, which assumes a PoS system, and iterator, which assumes we can do prefix scans over the storage (ie. it is a Merkle Tree, not a Merkle Trie).

I even searched Wikipedia for "Merkle Trie" and couldn't easily find out what it is, why it's different to a Merkle Tree, or why the difference is important.

[willclarktech]

Re the tutorial: I expected the section "First contract" to at least show me what a contract looks like, or maybe to get me to write one. But it's really just the intro to the tutorial, and we don't see any contract code until four sections later.

I think in general it's best to show people what we do and then provide explanations afterwards. The tutorial starts off with a detailed explanation of every known attack on Solidity contracts, which is a bit intimidating. I'd rather get my hands dirty with some code first, and then I'd have some context for the detailed explanation of the design decisions.

[ethanfrey]

Merkle Trie is the general name for Patricia Trie - ethereum 1.0 - or Sparse Merkle Tree - ethereu 2.0. We should link something there.

A trie uses one branch per 1-4 bytes of the key rather than a balanced btree algorithm. This leads to a shape invariant to insert order, but also means the depth is O(max key length in bits) rather than O(log(number of elements in the tree)). There are long discussions on advantages and disadvantages, but usually scattered around random crypto chats

[ethanfrey]

I think in general it's best to show people what we do and then provide explanations afterwards. The tutorial starts off with a detailed explanation of every known attack on Solidity contracts, which is a bit intimidating. I'd rather get my hands dirty with some code first, and then I'd have some context for the detailed explanation of the design decisions.

Good point

[ethanfrey]

This is kind of a meta-issue that is partly done. Let's keep this in mind when adding more docs, but I think the existing docs have been largely cleaned up.

[ethanfrey]

Mostly done, remaining work in #75