Docs revamp #5866
Docs revamp #5866
Conversation
Changing the name of the Haskell file in this contract example to reflect that we are now using a different example than before.
The changes here reflect feedback from Marshall on March 26, 2024, during our review discussion of this page.
|
Is there a particular reason to use md instead of rst? I'm not sure whether md allows importing code from Haskell modules like rst does. |
| #### Hardware and OS requirements | ||
|
|
||
| **Processing power** | ||
| - Minimum: Intel Core i5 or AMD equivalent |
There was a problem hiding this comment.
How were these requirements determined? I doubt you can't develop Plutus on an intel core i3, for example.
There was a problem hiding this comment.
I just did a little Googling to get a sense of some common recommended specs.
| #### GHC (Glasgow Haskell Compiler) | ||
|
|
||
| - GHC is the main compiler for Haskell with many extensions and optimizations. | ||
| - To install GHC, run `stack setup`. Stack will automatically install the appropriate version of GHC for your project. |
There was a problem hiding this comment.
I don't think we need to teach people how to install Stack, GHC and Cabal, since they are standard Haskell tooling. Also, if you are using Nix or Docker, they will already be installed for you.
I also don't think "stack setup" is the standard way of installing GHC.
There was a problem hiding this comment.
Good to know. Taking a step back to look at the bigger picture, we may need to revisit the question of how much detail is appropriate to include given our intended audience. I think I'll make a revised outline for review and discussion to simplify getting agreement about scope and detail.
|
|
||
| To verify your Cabal installation, run `cabal –version`. | ||
|
|
||
| ### Git |
There was a problem hiding this comment.
We definitely don't need to teach people how to install Git. It is so basic and not specific to Plutus.
| - macOS: macOS Catalina (10.15) or later | ||
| - Windows: While Windows can be used for Haskell development, it is less common and might require additional setup such as using Windows Subsystem for Linux (WSL2) to provide a Linux-compatible environment. | ||
|
|
||
| ### Tools |
There was a problem hiding this comment.
I suggest stripping out this whole subsection. This alone is enough: https://github.com/IntersectMBO/plutus/blob/master/doc/read-the-docs-site/quick-start.rst
There was a problem hiding this comment.
Looks like some great resources in that quick-start.rst file!
|
|
||
| An IDE provides a comprehensive environment for writing, testing, and debugging your Haskell code. Visual Studio Code (VS Code) is a widely used code editor that supports the Haskell extension. See [https://code.visualstudio.com/](https://code.visualstudio.com/). | ||
|
|
||
| ## Testing your environment setup |
There was a problem hiding this comment.
I don't think we need this. We are basically teaching people how to write hello world in Haskell. That's not our responsibility - we should assume users already know Haskell, and if they are new to Haskell, they can find this information (and much more materials for Haskell beginners) elsewhere.
There was a problem hiding this comment.
OK, good point.
| Before we start building our vesting smart contract, let's go over the following core concepts that underpin Plutus smart contracts. | ||
|
|
||
| ### Datum | ||
| In a vesting contract, the datum represents the state and conditions of the vesting agreement. It includes information such as the beneficiary's public key hash and the deadline for the vesting period. The datum is attached to the UTxO that holds the vested funds and is used by the contract's validator script to enforce the vesting conditions. It ensures that the funds can only be released to the beneficiary after the specified deadline has passed. |
There was a problem hiding this comment.
If we want to have a subsection explaining what Datum is, it's better to explain what it is in general, and then proceed to explain what it does in the specific context of a vesting contract.
Besides, if there's a section explaining core concepts, I think it should start with the EUTxO model.
|
|
||
| 1. Create a new directory for your project and navigate to it in your terminal. | ||
|
|
||
| 2. If you are using Nix, enter a Nix shell that provides the necessary development environment by running `nix develop` in your project directory. If you are not using Nix, make sure that all required C libraries are installed since PlutusTx depends on `cardano-base`, which in turn depends on cryptographic C libraries like `libblst`, `libsecp256k1`, and `libsodium`. |
There was a problem hiding this comment.
This part is no longer needed following #5864
| In a vesting contract, the datum represents the state and conditions of the vesting agreement. It includes information such as the beneficiary's public key hash and the deadline for the vesting period. The datum is attached to the UTxO that holds the vested funds and is used by the contract's validator script to enforce the vesting conditions. It ensures that the funds can only be released to the beneficiary after the specified deadline has passed. | ||
|
|
||
| ### Redeemer | ||
| A redeemer is a piece of data that is provided by the spending transaction. It is used by the validator script to make decisions during the validation process. The redeemer is used to pass dynamic information to the validator script that may not be known at the time the UTXO is created but is only known at the time the UTXO is being spent. In the context of a vesting contract, the redeemer is typically not used, since the contract's logic does not need any additional input from the transaction. Instead, the validation of the transaction is based solely on the datum (vesting conditions) and the script context, such as checking if the deadline has passed and if the transaction is signed by the beneficiary. However, if required, a redeemer could be used to provide additional arguments to the validator script. |
There was a problem hiding this comment.
In the context of a vesting contract, the redeemer is typically not used
The fact that this example does not need a redeemer suggests that it is not a very interesting example.
There was a problem hiding this comment.
I want to use a simple and straightforward example that is easy to understand from the perspective of someone who has never used Plutus. This is an example from the Plutus Pioneer Program. We can consider other examples if they would more effectively serve the purpose of this onboarding guide.
|
|
||
| ### Section 1: Importing the required modules and functions | ||
|
|
||
| ```haskell |
There was a problem hiding this comment.
We shouldn't have code inlined in the md files. The code needs to be put in a Haskell module and checked by CI.
There was a problem hiding this comment.
OK, good to know. Once we agree on the example we want to use here, would we use code block inclusions instead of inlining code to show each section we want to describe? I'm not sure how we would follow that practice while reviewing drafts. But once we have a documentation platform established for the revamp, then I imagine we could generate draft pages that include code blocks.
I'm working with the web dev team to determine whether we will stay with Read the docs using .rst files or Docusaurus where I would use .md files. So for now I'm using .md until we know what platform we'll be using for the revamp. The code block inclusion question is top of mind in our discussion with the web dev team. |
Thanks for reminding me about writing each sentence on a separate line. I will follow that practice. |
…ubleshooting. Brought over simple auction graphics and AuctionValidator haskell file.
…formation from Plutus developers about the topic of using Plutus Tx
…eems outdated since many components of it are no longer supported
zeme-wana
force-pushed
the
master
branch
2 times, most recently
from
a161078
to
db5cabb
Compare
This Draft PR is for the Plutus Core Plutus Tx documentation revamp project. I'll use nested PRs within this Draft PR until the docs revamp project reaches a to-be-defined level of maturity to merge with
master.