Docs revamp

doc/docs-revamp/README.md

@@ -0,0 +1,19 @@
+# Plutus docs revamp project
+
+This outline shows the proposed reorganized structure for the Plutus Core Plutus Tx documentation revamp. 
+
+# Reorganized top levels
+
+## 1. [Introduction](introduction.md)
+## 2. [Core concepts](core-concepts.md)
+## 3. [Developer onboarding and quick setup](dev-onboarding-quick-setup.md)
+   - Review comments incorporated as of March 26. 
+## 4. [Simple example](simple-example.md)
+## 5. [Using Plutus Tx](using-plutus-tx.md)
+## 6. [Working with scripts](working-with-scripts.md)
+## 7. [Working with Plutus Core](working-with-plutus-core.md)
+## 8. [Reference](reference.md)
+## 9. [Troubleshooting](troubleshooting.md)
+## 10. [FAQ](faq.md)
+   - Draft list of questions in place. Changes to the questions are pending. 
+

doc/docs-revamp/core-concepts.md

@@ -0,0 +1,35 @@
+---
+title: "Core concepts"
+description: "A set of definitions of core concepts"
+date: 2024-03-12
+---
+
+# Section 2. Core concepts
+
+## Resources to inform this section: 
+- Blog: [Plutus Tx: compiling Haskell into Plutus Core](https://iohk.io/en/blog/posts/2021/02/02/plutus-tx-compiling-haskell-into-plutus-core/), by Michael Peyton Jones, Feb. 2021
+   - This is several years old, but the underlying essential definitions and concepts are still applicable. 
+- Draft document: [Smart contracts security and best practices](https://docs.google.com/document/d/1CrWYmG-I-Z2KeB06pPM9TqvjpSgpgt8e4ipLY9vJDKE/edit?usp=sharing) being prepared by Luka Kurnjek, Education team
+- [An Introduction to Plutus Core](https://blog.hachi.one/post/an-introduction-to-plutus-core/)
+
+## Core concepts
+- Names, terminology, ecosystem
+- Ledger
+- Scripts and the EUTXO model
+- Different kinds of scripts
+- Plutus Core
+- Plutus Tx
+- Plutus language versions
+
+## Understanding the Plutus platform
+- What is Plutus?
+	- The relationship between Plutus, Haskell, and Cardano
+- Anatomy of a smart contract
+- A thumbnail sketch of Plutus smart contract developer workflow
+   - Most common tasks
+- Plutus Components:
+	- Plutus Core (The foundational layer, low-level programming language for smart contracts on Cardano.)
+	- Plutus Tx (The library for writing high-level Haskell code that gets compiled down to Plutus Core)
+- The Extended UTXO Model (EUTXO):
+	- How it differs from the account-based model
+	- Advantages for smart contracts

doc/docs-revamp/faq.md

@@ -0,0 +1,42 @@
+---
+title: "FAQ"
+description: "Frequently asked questions"
+date: 2024-03-12
+---
+
+# Section 10. FAQ
+
+Draft FAQ for Plutus Core Plutus Tx
+
+_NOTE: Some comments made in the Google doc are not reflected here yet._ 
+
+Stage 1: Identify and refine the questions
+
+QUESTION TO ALL REVIEWERS: Can you think of questions that haven’t been included here yet that are likely to be on the minds of people who are coming to the documentation for the very first time? 
+
+Stage 2: Develop answers to the questions
+
+Below is a draft list of questions for consideration and review. Please add to the list if you have more suggestions, and edit/comment if a question should be clarified or modified to make more sense. 
+
+Once we have reviewed and more or less settled on the questions, I’ll schedule a meeting inviting anyone who is available and interested to collect your thoughts to help inform the answers. Then I’ll circulate another draft that includes answers for review. 
+
+- What are the prerequisites for developing Plutus smart contracts on the Cardano blockchain? 
+- What are the benefits of using Haskell and Plutus for smart contract development on Cardano?
+- Can you explain the relationship between Haskell, Plutus, Plutus Core, and Plutus Tx in the context of Cardano smart contracts?
+- How do I set up my development environment for Plutus and Haskell?
+- What tools and resources are essential for a beginner to start developing with Plutus?
+- Can you dissect the anatomy of a Plutus smart contract to highlight its core elements?
+- How do you write basic Plutus Tx programs, and what are the foundational principles?
+- What libraries are most beneficial for writing Plutus Tx scripts, and how do they enhance development?
+- How do I create a new Cabal package for my Plutus project?
+- How can developers declare and manage Plutus Tx dependencies within their projects?
+- What are the key components of an on-chain validator in Plutus? 
+- Could you explain the process of writing an on-chain validator script and its role in a Plutus smart contract?
+- What are the basics of Template Haskell relevant to Plutus developers, and how does it facilitate smart contract development?
+- What are the best methods you recommend for Plutus smart contract developers to use to test and/or simulate their smart contracts?
+- What are some common errors beginners might encounter when starting with Plutus, and how can they be resolved?
+- What are the best practices for creating and submitting transactions using an off-chain framework in Plutus?
+- How does interfacing between Plutus Tx and off-chain code work, and what are the common patterns?
+- What guidelines should be followed when writing validator scripts in Plutus? 
+- What guidelines should be followed when writing minting policies in Plutus?
+

doc/docs-revamp/introduction.md

@@ -0,0 +1,22 @@
+---
+title: "Introduction"
+description: "A brief introduction to Plutus and its significance in the Cardano ecosystem"
+date: 2024-03-12
+---
+
+TBD -- outline only
+
+# Section 1. Introduction
+
+- Welcome to Plutus: A brief introduction to Plutus and its significance in the Cardano ecosystem.
+- Target audience: 
+	- Description of assumed knowledge (basic Haskell) and what the documentation aims to cover.
+	- Identify the variety of primary roles we expect people to have who would be interested in the docs. 
+- Document overview: Briefly outline the key sections and what developers will learn.
+
+## Introductory resources
+- Reference to the [Plutus Pioneer Program Gitbook](https://iog-academy.gitbook.io/plutus-pioneers-program-fourth-cohort/) (gitbook.io)
+- Awareness of the Plutus Pioneer Program github page as a valuable resource: 
+	- [https://github.com/input-output-hk/plutus-pioneer-program](https://github.com/input-output-hk/plutus-pioneer-program)
+- Reference to the [IOG Academy Haskell Course](https://www.youtube.com/playlist?list=PLNEK_Ejlx3x1D9Vq5kqeC3ZDEP7in4dqb)
+- IOG's technical community on Discord for PPP

doc/docs-revamp/reference.md

@@ -0,0 +1,25 @@
+---
+title: "Reference"
+description: "TBD"
+date: 2024-03-12
+---
+
+# Section 8. Reference
+
+- Plutus Tx compiler options
+- Optimization techniques for Plutus scripts
+   - Identifying problem areas
+   - Using strict let-bindings to avoid recomputation
+   - Specializing higher-order functions
+   - Common sub-expression elimination
+   - Using `error` for faster failure
+- Common weaknesses
+   - Double satisfaction
+   - Hard limits
+- Plutus on Cardano
+   - Plutus language changes
+   - Upgrading to Vasil and Plutus script addresses
+   - Cost model parameters
+- Glossary
+- Bibliography
+

doc/docs-revamp/simple-example.md

@@ -0,0 +1,15 @@
+---
+title: "Simple example"
+description: "A Plutus script for an auction smart contract"
+date: 2024-03-12
+---
+
+# Section 4. Simple example
+
+- Plutus script for an auction smart contract
+- The EUTXO model, datum, redeemer and script context
+- Auction 
+   - Properties
+   - Life cycle
+- Plutus Tx code
+

doc/docs-revamp/troubleshooting.md

@@ -0,0 +1,12 @@
+---
+title: "Troubleshooting"
+description: "Troubleshooting"
+date: 2024-03-12
+---
+
+# Section 9. Troubleshooting
+
+- Plugin errors
+- Haskell language server issues
+- Error codes
+

doc/docs-revamp/using-plutus-tx.md

@@ -0,0 +1,21 @@
+---
+title: "Using Plutus Tx"
+description: ""
+date: 2024-03-12
+---
+
+# Section 5. Using Plutus Tx
+
+- Template Haskell preliminaries
+- Writing basic Plutus Tx programs
+- Functions and datatypes
+- Typeclasses
+- The Plutus Tx Prelude
+- Lifting values
+- Plutus Tx Compiler Options
+- GHC Extensions, Flags and Pragmas
+   - Extensions
+   - Flags
+   - Pragmas
+- Alternatives to Plutus Tx
+

doc/docs-revamp/working-with-plutus-core.md

@@ -0,0 +1,9 @@
+---
+title: "Working with Plutus Core"
+description: "TBD"
+date: 2024-03-12
+---
+
+# Section 7. Working with Plutus Core
+
+- TBD

doc/docs-revamp/working-with-scripts.md

@@ -0,0 +1,28 @@
+---
+title: "Working with scripts"
+description: "writing validator scripts, writing minting policies, creating and submitting transactions using an off-chain framework, libraries for writing Plutux Tx scripts, exporting scripts datums and redeemers, profiling the budget usage of Plutus scripts"
+date: 2024-03-12
+---
+
+# Section 6. Working with scripts
+
+- Writing basic validator scripts
+   - Validator arguments
+   - The Data type
+   - Signaling failure
+   - Validator functions
+   - Plutus script context versions
+- Writing basic minting policies
+   - Minting policy arguments
+   - Plutus script context versions
+   - Writing minting policies
+   - Other policy examples
+- Creating and submitting transactions using an off-chain framework
+- Libraries for writing Plutus Tx scripts
+- Exporting scripts, datums and redeemers
+- Profiling the budget usage of Plutus scripts
+   - Compiling a script for profiling
+   - Acquiring an executable script
+   - Running the script
+   - Analyzing the results
+