Documentation suggestions

[devbugging]

Here are some documentation gaps I have found while developing.

Flow Building Blocks There is no document describing "flow entities" in language-agnostic and easy-to-understand terms. Entities that make the Flow network such as:

• accounts,
• blocks,
• transactions,
• collections,
• networks,
• nodes

It would be great to have a page for each of those entities where we would describe what the entity is, what role does it play on the network, how it gets created and how you interact with it etc all that language agnostic. Something similar to: https://ethereum.org/en/developers/docs/accounts/ or https://ethereum.org/en/developers/docs/transactions/ An example of questions this document would answer:

• What are possible transaction statuses and what they mean,
• What is the purpose of each Flow network (mainnet, testnet, canarynet, emulator),
• How are accounts created etc etc

Hello Flow A quick introduction for newcomers about the Flow concepts. Slimmed-down version of https://www.onflow.org/primer with easy to understand explanation of concepts. It would include titles such as: What is Flow? What is Flow token? How Flow works (multi-node arch), What is smart contract / Cadence?

Cadence by Example / Tour of Cadence A document that offers a similar experience for learning to how you learn Go (by example) https://tour.golang.org/welcome/1 (it doesn't need to be interactive, as long as it's an example with explanation of concepts used is good enough). Another great example is Solidity: https://solidity-by-example.org/

[bebner]

Mostly +1 on these points, and will try to get something started on these points as soon as the education pod starts again.

Flow Building Blocks Good ideas in this regard. I think we do have some explanations, but they are scattered over the documentation. Especially for accounts we already have pretty good descriptions, same for transactions. What we're missing is I think descriptions for:

• blocks
• collections
• networks (esp. Canarynet)

And it does make a ton of sense to combine them in one place, like Ethereum's docs that you suggested.

Hello Flow Would be okay to do it, but I don't think it is as critical in my opinion. Sounds like a short FAQ to me.

Cadence by Example / Tour of Cadence I love the Go docs you mentioned, they are awesome. On the marketing side, we have already started something similar, called "Cadence Snippets", see below. Would this be a sufficient alternative already?

[devbugging]

Great, thank you.

I think we do have some explanations, but they are scattered over the documentation. Especially for accounts we already have pretty good descriptions, same for transactions.

I would say there is much more needed than what we have about transactions here: https://docs.onflow.org/concepts/transaction-signing/#anatomy-of-a-transaction assuming you mean this document. For example, what is the transaction lifecycle, what each status means, etc. Same with accounts and how storage works and also storage paths etc. There's a lot of gaps we don't see anymore because of the knowledge we have. Having all of this in one place would be great for sure. And yes, I agree, a lot of information is scattered all over the docs and that is a problem on it's own, data gets outdated because "single sources of truth" are not defined, after they would be defined all other documents would need to link to that not have their own copy, but since there are gaps in docs now a lot of documents need to describe some concepts there instead of linking (because there is nowhere to link right now).

Hello Flow

Yeah, that targets "blockchain noobies" which might not yet be our target audience so I agree.

Cadence by Example / Tour of Cadence

Yes, this looks awesome, but will there be a part of documentation containing this examples at some later point or will that just be social posts?

[kerrywei]

+1 on having documentation for blocks/collections, especially for block -- there are many Flow access APIs needs to deal with block ID/height, which are not really properly explained in the doc.