Cadence Tutorials - Hello World

[noisygerman]

Listing issues or sections with room for improvement found while reading through the cadence/tutorial/02-hello-world section of the docs.

Hello World

1. Lets write and deploy our first smart contract! => Let's write... and I'd make this part of the paragraph. Hello Wold is a header already. It seems a bit odd that we state this here and then explain what a smart contract is. Moving this to the end of the paragraph would allow us to transition from explanation to interaction.

2. Box Open the starter code for this tutorial in the Flow Playground: - I'd suggest we move this close to where we actually get to interact with the templates on that page - or we could move this section to a separate page, explaining conventions, assumptions and organisation. See Dummies books introduction pages or similar.

3. Paragraph:

   A smart contract is a program that verifies and executes the performance of a contract without the need for a trusted third party. Programs that run on blockchains are commonly referred to as smart contracts because they mediate important functionality (such as currency) without having to rely on a central authority (like a bank).

   • we say the same things twice in the paragraph
   • we provide background information here that, in my opinion, would be better stored in an appendix or more generic, Blockchain or Flow-specific set of pages of the documentation. As a developer, I want to get going here.

4. Section Accounts and Transactions

   1. Same as for the paragraph above. It would make sense to move this entire section to an appendix or general Flow documentation section - the Flow Glossary section already elaborates on this.

   2. accounts link is broken

   3. All persistent state and its interfaces (the ways to interact with it) - Not clear to me:

      • what does it refer to here? The state? The account?
      • The state of what?

   4. This means that support for multi-sig wallets is built...

      We should do our best to avoid jargon/abbreviations in documentation(multisingature is still jargon, but more intuitively understood, even by ESL readers). We should also provide links - at least to Wikipedia or similar - to allow anyone to quickly lookup information on subjects like this one.

      Maybe:

      Accounts are secured by one or more private key. This means that support for multisignature wallets is built into the protocol by default.

   5. Section

      An account is divided into two main areas:

      Since we don't see this in the playground at this point, I'm not sure this information aides us here - again, this should be put into a glossary, an appendix, to a more general page about this subject.

      1. Section

         This is the area that stores programs known as smart contracts that contain type definitions, fields, and functions that are related to a common functionality. This can also hold contract interfaces, which are basically program guidelines that other contracts can import and implement. This area cannot be directly read from in a transaction, but the owner of an account can directly overwrite contracts that are stored in it.

         We have already established what Smart Contracts are. So we should use that term now, potentially linking back to the definition in the glossary/appendix/Flow docs. Maybe:

         Smart contracts composed of type definitions, fields and common functions are stored here, as well as Smart Contract Interfaces.

         If we feel that the information provided in the glossary for Contract Interfaces is not sufficient, we should enhance the documentation there, instead of overloading the Hello World page with information not important for the tutorial itself. Seperation of Concerns in documentation, ya dig? 🙂

      2. Section

         The second area is the account filesystem. This area is accessible in transactions and is where an account stores the objects that they own and the capabilities for controlling how these objects are accessed. Objects are stored under paths in the account filesystem. Paths consist of a domain and an identifier.

         • This numbered list item serves as the introduction for the whole next section. This is confusing in my opinion. The filesystem should be explained here by itself in the glossary/appendix or in its own page.
         • The wording of this item is confusing as well.

   Each of the paths section would be best introduced when used in a tutorial somewhere (aside from explaining these in the glossary)

   1. Diagram: It would be great if we had relatable examples here, rather than using foo.bars.
   2. Transaction section: guess what I'll write next: yes, should be in its own section in a glossary/appendix, should be explained in the context of a tutorial explaining transactions 🏆

[10thfloor]

@noisygerman This is great! Thank you for your detailed notes. Do you think you'd have time to create a PR with some of these improvements? I'm happy to iterate with you.