Enhancing Node Differentiation in Masa Protocol Documentation

[lacyg4]

Problem Statement

Users are struggling to distinguish between worker nodes and oracle nodes in Masa's protocol due to unclear documentation. This ambiguity hinders effective decision-making for our clients.

Detailed Description To address this, we need to revamp our documentation on worker and oracle nodes. The goal is to provide clear, comprehensive information that allows users to easily understand each node's role, use cases, and comparative advantages.

Examples of user tension:

Acceptance Criteria

Oracle Node Section Updates Introduction page:

• [ ] Add a concise definition of an oracle node, explaining its primary function within the Masa protocol.
  • [ ] Example: "An oracle node is responsible for fetching and verifying external data to be used within the blockchain network."

• [ ] Add a Role and Responsibilities headliner:
  • [ ] Elaborate on the specific duties of oracle nodes, such as data validation and integration.
  • [ ] Include diagrams illustrating how oracle nodes interact with other components in the network.

• [ ] Add Comparative Analysis:
  • [ ] Create a table comparing oracle nodes and worker nodes on aspects like purpose, data handling, and network roles.
  • [ ] Example Parameters: Data Source, Processing Power, Use Cases. Include social data scraping as an example so users understand the difference between what data is available to them as an oracle node vs. worker node (I.E.if you're running an oracle node you have access to X twitter data vs. running as a worker node only have access to Y twitter data).

• [ ] Add Real-World Applications:
  • [ ] Provide examples of how oracle nodes are used in real-world scenarios, such as in DeFi applications so it's clear to the user if it makes sense for them to operate as an oracle node vs. worker node.

• [ ] Add Visual Aids:
  • [ ] Add visual aids, such as flowcharts and diagrams, to help users understand the placement and function of oracle nodes within the network.
  • [ ] Ensure the visuals are clear and labeled.

• [ ] Add a Glossary and FAQs parent category (below "Quickstart")
  • [ ] Add a glossary section to include definitions of key terms related to oracle nodes.
  • [ ] Add a FAQ section addressing common questions and issues related to oracle nodes.

Worker Node Section updates: Introduction page:

• [ ] Offer a clear definition of a worker node, highlighting its role in the Masa protocol.
  • [ ] Example: "A worker node performs computational tasks and processes transactions within the network."

• [ ] Add a Role and Responsibilities headliner:
  • [ ] Detail the specific functions of worker nodes, such as transaction processing and computational tasks.
  • [ ] Include diagrams showing worker nodes' interaction with other network components.

• [ ] Add a Comparative Analysis:
  • [ ] Use the same table format from the oracle node section to compare and contrast worker nodes and oracle nodes.
  • [ ] Ensure the table is placed in both sections for easy reference.

• [ ] Add Specific Use Cases:
  • [ ] Highlight specific use cases where worker nodes are crucial, such as in high-performance computing tasks so it's clear to the user if it makes sense for them to operate as an oracle node vs. worker node.
  • [ ] Include real-world examples to illustrate these use cases.

• [ ] Add Visual Aids:
  • [ ] Add visuals such as network topology diagrams that depict the role and placement of worker nodes.
  • [ ] Ensure the visuals are clear and labeled.

• [ ] Updates to Quick Start section
  • [ ] Add loom vide: https://github.com/masa-finance/masa-oracle/assets/167825977/74df6daf-65d3-456d-87e9-8f98ca0e2d0d

• [ ] Add a "Glossary and FAQs" parent category (below "Quickstart")
  • [ ] Update the glossary to include definitions of key terms related to worker nodes.
  • [ ] Add a FAQ section addressing common questions and issues related to worker nodes.

[lacyg4]

@giovaroma we also want to make clear the difference between scraping data as an oracle node vs. worker node - I made a note to include this in the comparative analysis table, but we should figure out where else we should clarify these. For example, is it worth going into each social scaping parent category page - I.E. twitter data for example and providing this clarity? Also good idea to include in FAQ page. Just some thoughts I've got swirling and for us to discuss/ collab on our prod sync tomorrow AM.