docs(documentation): added guides and improved overall docs

apps/website/docusaurus.config.ts

@@ -103,6 +103,9 @@ async function getConfig(): Promise<Config> {
       blogPosts: Array.isArray(blogPosts) ? blogPosts : [],
     },
     themeConfig: {
+      prism: {
+        additionalLanguages: ["bash"],
+      },
       image: "img/maci-card.png",
       navbar: {
         title: "MACI",

apps/website/src/scripts/setupSolidityDocs.ts

@@ -6,7 +6,7 @@ import { copyDirectory, generateToC, insertIndexPage } from "./utils";
 // where to move the solidity doc files over
 const solidityDocDir = path.resolve(
   __dirname,
-  "../../versioned_docs/version-v2.x/developers-references/smart-contracts/solidity-docs",
+  "../../versioned_docs/version-v2.x/technical-references/smart-contracts/solidity-docs",
 );
 // the origin folder (from the contracts package)
 const sourceDir = path.resolve(__dirname, "../../../packages/contracts/docs");

apps/website/src/scripts/setupTypedoc.ts

@@ -82,12 +82,12 @@ function defineTargetDirectory() {
       const versionContentJson = JSON.parse(versionContent) as string[];
       return path.resolve(
         __dirname,
-        `../../versioned_docs/version-${versionContentJson[0]}/developers-references/typescript-code/typedoc`,
+        `../../versioned_docs/version-${versionContentJson[0]}/technical-references/typescript-code/typedoc`,
       );
     }
   }
 
-  return path.resolve(__dirname, "../../docs/developers-references/typescript-code/typedoc");
+  return path.resolve(__dirname, "../../docs/technical-references/typescript-code/typedoc");
 }
 
 if (fs.existsSync(TYPEDOC_DIR)) {

apps/website/versioned_docs/version-v2.x/contributing/_category_.json

@@ -1,8 +1,4 @@
 {
   "label": "Contributing",
-  "position": 10,
-  "link": {
-    "type": "generated-index",
-    "description": "MACI's contribution guidelines."
-  }
+  "position": 10
 }

apps/website/versioned_docs/version-v2.x/contributing/project-ideas.md

@@ -0,0 +1,78 @@
+---
+title: MACI Project Ideas
+description: Community-sourced ideas of projects you could build with MACI
+sidebar_label: MACI Project ideas
+sidebar_position: 3
+---
+
+# Project Ideas
+
+### 1. Decentralized Governance Platform
+
+**Idea:** Create a decentralized governance platform for DAOs (Decentralized Autonomous Organizations) using the Scaffold ETH 2 + MACI Voting Template. Enable DAO members to propose and vote on governance decisions securely and anonymously.
+
+**Features:**
+
+- Proposal creation and submission
+- Secure, anonymous voting using MACI
+- Transparent results display
+- Integration with existing DAO frameworks
+
+### 2. Secure Polling System for Communities
+
+**Idea:** Develop a secure and private polling system for online communities, such as social media groups, forums, or local organizations. This system can be used for decision-making, surveys, or feedback collection.
+
+**Features:**
+
+- User-friendly poll creation and management interface
+- Anonymized vote submission
+- Real-time poll results visualization
+- Admin dashboard for poll oversight
+
+### 3. Private Election System for Institutions
+
+**Idea:** Build a private and secure election system for educational institutions, corporate boards, or non-profits. Ensure that election processes are transparent, fair, and resistant to manipulation.
+
+**Features:**
+
+- Secure voter registration process
+- Anonymous and tamper-proof voting
+- Detailed results analytics
+- Audit logs and election certification
+
+### 4. Anonymous Feedback System
+
+**Idea:** Implement an anonymous feedback system for companies or organizations to collect honest feedback from employees or customers. Guarantee the privacy of the respondents to encourage open and honest communication.
+
+**Features:**
+
+- Anonymous feedback submission
+- Secure handling of sensitive information
+- Aggregated feedback reports
+- Admin tools for feedback analysis
+
+### 5. Decentralized Survey Platform
+
+**Idea:** Create a decentralized survey platform for academic research or market analysis. Utilize MACI's privacy features to ensure respondent confidentiality and data integrity.
+
+**Features:**
+
+- Customizable survey creation
+- Anonymized responses
+- Secure data storage and processing
+- Results aggregation and visualization
+
+### 6. Blockchain-based Voting for Public Elections
+
+**Idea:** Develop a blockchain-based voting system for municipal or state-level public elections. Focus on enhancing transparency, security, and voter anonymity.
+
+**Features:**
+
+- Robust voter registration and verification
+- Anonymous vote casting and tallying
+- Transparent and verifiable election results
+- Compliance with electoral regulations
+
+## Join the conversation
+
+The MACI core team maintains a wishlist of community-sourced ideas to build with/for/on MACI. Check out our ["Project ideas to build with MACI" GitHub Discussion](https://github.com/privacy-scaling-explorations/maci/discussions/1136) for the up-to-date list! We encourage you to find inspiration here and comment in the discussion to suggest ideas of your own.

apps/website/versioned_docs/version-v2.x/core-concepts/_category_.json

@@ -1,8 +1,4 @@
 {
   "label": "Core Concepts",
-  "position": 3,
-  "link": {
-    "type": "generated-index",
-    "description": "Understand MACI's core concepts."
-  }
+  "position": 5
 }

apps/website/versioned_docs/version-v2.x/core-concepts/hashing-and-encryption.md

@@ -2,7 +2,7 @@
 title: Hashing and Encryption
 description: A short introduction of the main primitives used by MACI
 sidebar_label: Hashing and Encryption
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 ### Hash Functions

apps/website/versioned_docs/version-v2.x/core-concepts/maci-keys.md

@@ -2,7 +2,7 @@
 title: MACI Keys
 description: A short introduction of MACI's keys
 sidebar_label: Maci Keys
-sidebar_position: 1
+sidebar_position: 2
 ---
 
 ## Elliptic Curves

apps/website/versioned_docs/version-v2.x/core-concepts/merkle-trees.md

@@ -9,7 +9,7 @@ MACI uses different types of merkle trees to store and manage data. On chain, a
 
 ## Accumulator queue
 
-This contract holds [messages](/docs/developers-references/smart-contracts/Poll#publishmessage) sent by users. When a leaf is inserted into the `AccQueue`, the merkle root is not updated yet, instead the leaf is updated or the root of a subtree is re-computed. The smart contract exposes three functions:
+This contract holds [messages](/docs/technical-references/smart-contracts/Poll#publishmessage) sent by users. When a leaf is inserted into the `AccQueue`, the merkle root is not updated yet, instead the leaf is updated or the root of a subtree is re-computed. The smart contract exposes three functions:
 
 - `enqueue(leaf)`: Enqueues a leaf into a subtree
   four out of five times it is invoked, an enqueue operation may or may not require the contract to perform a hash function. When it does, only up to $t_d$ required number of hashes need to be computed
@@ -20,4 +20,4 @@ This contract holds [messages](/docs/developers-references/smart-contracts/Poll#
 
 ## LazyIMT
 
-A LazyIMT is a Merkle tree that is updated lazily. It is used to [store the state leaves](/docs/developers-references/smart-contracts/MACI#signup) of the users. The "lazy" tree performs the minimum number of hashes necessary to insert elements in a tree. This means if there is only a left element the parent hash is not calculated until a corresponding right element exists, to avoid having an intermediate hash that will change in the future. This tree is designed for roots that are infrequently accessed onchain.
+A LazyIMT is a Merkle tree that is updated lazily. It is used to [store the state leaves](/docs/technical-references/smart-contracts/MACI#signup) of the users. The "lazy" tree performs the minimum number of hashes necessary to insert elements in a tree. This means if there is only a left element the parent hash is not calculated until a corresponding right element exists, to avoid having an intermediate hash that will change in the future. This tree is designed for roots that are infrequently accessed onchain.

apps/website/versioned_docs/version-v2.x/overview/workflow.md → apps/website/versioned_docs/version-v2.x/core-concepts/workflow.md

@@ -2,7 +2,7 @@
 title: MACI Workflow
 description: Overview of the MACI workflow
 sidebar_label: Workflow
-sidebar_position: 4
+sidebar_position: 1
 ---
 
 <!-- TODO: create flowcharts, similar to Kyle's (but make light/dark mode compatible) -->
@@ -69,11 +69,11 @@ See our [smart contract docs](/docs/category/smart-contracts) or our [contract s
 
 ### MACI.sol
 
-The MACI contract is responsible for registering user signups by recording the initial public key for each user (via the [`signUp` function](/docs/developers-references/smart-contracts/solidity-docs/MACI#signup-1)). To conduct a voting round, the coordinator can deploy a Poll via MACI (with the [`deployPoll` function](/docs/developers-references/smart-contracts/solidity-docs/MACI#deploypoll)).
+The MACI contract is responsible for registering user signups by recording the initial public key for each user (via the [`signUp` function](/docs/technical-references/smart-contracts/solidity-docs/MACI#signup-1)). To conduct a voting round, the coordinator can deploy a Poll via MACI (with the [`deployPoll` function](/docs/technical-references/smart-contracts/solidity-docs/MACI#deploypoll)).
 
 ### Poll.sol
 
-The Poll contract is where users submit their votes (via the [`publishMessage` function](/docs/developers-references/smart-contracts/solidity-docs/Poll#publishmessage)). One MACI contract can be used for multiple Poll contracts. In other words, a user that signed up to the MACI contract can vote on multiple issues, with each issue represented by a distinct Poll contract.
+The Poll contract is where users submit their votes (via the [`publishMessage` function](/docs/technical-references/smart-contracts/solidity-docs/Poll#publishmessage)). One MACI contract can be used for multiple Poll contracts. In other words, a user that signed up to the MACI contract can vote on multiple issues, with each issue represented by a distinct Poll contract.
 
 ### MessageProcessor.sol and Tally.sol
 
@@ -120,13 +120,13 @@ At this point, the coordinator must process all the messages, tally the results,
 
 Once the voting period has completed for a specific poll, the coordinator will use the `MessageProcessor` contract to first prove that they have correctly decrypted each message and applied them to correctly create an updated state tree. This state tree keeps an account of all the valid votes that should be counted. So, when processing the messages, the coordinator will not keep messages that are later overridden by a newer message inside the state tree. For example, if a user votes for option A, but then later sends a new message to vote for option B, the coordinator will only count the vote for option B.
 
-The coordinator must process messages in batches so that proving on chain does not exceed the data limit. The coordinator then creates a zk-SNARK proving their state tree correctly contains only the valid messages. Once the proof is ready, the coordinator calls [`MessageProcessor.processMessages()`](/docs/developers-references/smart-contracts/solidity-docs/MessageProcessor#processmessages), providing a hash of the state tree and the zk-SNARK proof as an input parameters.
+The coordinator must process messages in batches so that proving on chain does not exceed the data limit. The coordinator then creates a zk-SNARK proving their state tree correctly contains only the valid messages. Once the proof is ready, the coordinator calls [`MessageProcessor.processMessages()`](/docs/technical-references/smart-contracts/solidity-docs/MessageProcessor#processmessages), providing a hash of the state tree and the zk-SNARK proof as an input parameters.
 
 The `MessageProcessor` contract will send the proof to a separate verifier contract. The verifier contract is specifically built to read MACI zk-SNARK proofs and tell if they are valid or not. So, if the verifier contract returns true, then everyone can see on-chain that the coordinator correctly processed that batch of messages. The coordinator repeats this process until all messages have been processed.
 
 #### Tally Results
 
-Finally, once all messages have been processed, the coordinator tallies the votes of the valid messages (off-chain). The coordinator creates a zk-SNARK proving that the valid messages in the state tree (proved in Process Messages step) contain votes that sum to the given tally result. Then, they call [`Tally.tallyVotes()`](/docs/developers-references/smart-contracts/solidity-docs/Tally#tallyvotes) with a hash of the correct tally results and the zk-SNARK proof. Similarly to the processMessages function, the `tallyVotes` function will send the proof to a verifier contract to ensure that it is valid.
+Finally, once all messages have been processed, the coordinator tallies the votes of the valid messages (off-chain). The coordinator creates a zk-SNARK proving that the valid messages in the state tree (proved in Process Messages step) contain votes that sum to the given tally result. Then, they call [`Tally.tallyVotes()`](/docs/technical-references/smart-contracts/solidity-docs/Tally#tallyvotes) with a hash of the correct tally results and the zk-SNARK proof. Similarly to the processMessages function, the `tallyVotes` function will send the proof to a verifier contract to ensure that it is valid.
 
 <!-- "hash of the correct tally results" - so are the final results actually put on chain? or just a hash?? -->