Make part 1, 2, and 3 of Cadence Tutorial more interactive and streamlined #172
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
briandoyle81
changed the title
| @@ -1,9 +1,9 @@ | |||
| --- | |||
| archived: false | |||
| draft: false | |||
| title: 2. Hello World | |||
There was a problem hiding this comment.
Removing the 2. makes it inconsistent with the numbering scheme in the sidebar
There was a problem hiding this comment.
I'm removing the numbers for all of them eventually. IMO it makes it look cluttered and they're displayed in order anyways. Happy to discuss if anyone disagrees!
docs/tutorial/01-first-steps.md
Outdated
| The Flow playground comes with pre-created accounts that you can use automatically. | ||
| :::warning | ||
|
|
||
| Flow is different from most other blockchains in that contracts, assets, and information owned by a user or associated with their wallet address **are stored in the user's account**. |
There was a problem hiding this comment.
Because this is beginner friendly, would elaborate how in other chains like Ethereum accounts are just keys and the ledger just points to what public key owns what assets, almost like how blacksmiths used to have notes about who held what gold they stored whereas Flow is like having the gold in your pocket. Reason being that the reader might not know how it works on other chains and this might be exciting/interesting to them
|
|
||
| #### What is an Account? | ||
| On Flow Cadence, **smart contracts are upgradeable**. If you make a mistake, you can often [update] it, constrained by some rules, in a public and transparent manner. |
There was a problem hiding this comment.
Don't think we need 'Flow' here, we don't use it elsewhere we reference Cadence.
There was a problem hiding this comment.
I'm explicitly saying "Flow Cadence" and "Flow EVM" everywhere to try and help separate which we're talking about while highlighting that they're on Flow with all the benefits
There was a problem hiding this comment.
I'd double click this convention with @SeanRobb so we're consistent everywhere
| "Hello, World!" | ||
| ``` | ||
|
|
||
| In Cadence, we have the resources to leave very detailed error messages. Check out the error messages in the [Non-Fungible Token Contract] and [Generic NFT Transfer transaction] in the Flow NFT GitHub repo for examples of production error messages. |
There was a problem hiding this comment.
We should hyperlink to the examples
There was a problem hiding this comment.
They're linked! Reference-style links. Or did that not work for you?
There was a problem hiding this comment.
Oh you mean like Wikipedia? Hmm, why not just link directly?
There was a problem hiding this comment.
Not like wikipedia. Clicking the link where it is on the page goes directly to the link in a new window. It renders and behaves exactly the same as the inline style of links. But when reviewing the raw file, it will jump you down to the actual link at the bottom if you click on it.
Doing it this way improves the readability of the raw document and you can reuse links, so you don't have to put them inline every time you want to link to something, which discourages people from linking as much as is appropriate, and you don't have to update 10 of them if the link changes.
| [nil-coalescing operator (`??`)]: ../language/operators.md#nil-coalescing-operator- | ||
| [Non-Fungible Token Contract]: https://github.com/onflow/flow-nft/blob/master/contracts/NonFungibleToken.cdc#L115-L121) | ||
| [Generic NFT Transfer transaction]: https://github.com/onflow/flow-nft/blob/master/transactions/generic_transfer_with_address_and_type.cdc#L46-L50 |
There was a problem hiding this comment.
Don't think we need these here if we can link them when we first referecne. Also looks a bit strange with the full link.
There was a problem hiding this comment.
Reference-style links! These don't render. It lets you just wrap your [links] and not interrupt the readability of the raw doc.
| when assigned to a different variable, | ||
| when passed as an argument to a function, | ||
| and when returned from a function. | ||
| They are **moved** when used as an initial value for a constant or variable, when assigned to a different variable, when passed as an argument to a function, and when returned from a function. |
There was a problem hiding this comment.
Here and below: It looks like only the newlines/line breaks got removed from the original content.
The line breaks are intentional, they are "Semantic Line Breaks": They are ignored in the rendered output, but are useful in the source Markdown, because they keep lines limited to a certain length (<=100) like in source code, and make it easier to review changes.
There was a problem hiding this comment.
I've worked with both methods before and find removing semantic line breaks to generally improve workflow for writing, editing, and updating docs.
Most editors can be set to wrap the text when viewing it, and by not having the line breaks it's much easier to edit and wordsmith the text because updates automatically display similar to how they'd appear on the page without having to save to autoformat, or run a script to rebreak at 80 wide.
No description provided.