Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DO NOT MERGE] New proposed structure #872

Open
wants to merge 1 commit into
base: development
Choose a base branch
from

Conversation

dragos-rebegea
Copy link
Contributor

@dragos-rebegea dragos-rebegea commented Apr 17, 2024

Description of the pull request (what is new / what has changed)

This is the proposed new structure of the documentation:

New MultiversX Documentation Structure

1. Getting Started

  • Welcome to MultiversX
  • Technology Overview
  • Architecture Overview
  • Glossary
  • Entities
  • Chronology
  • Setup and Configuration
    • Installing mxpy
    • Configuring mxpy
    • CLI Overview
    • Build Reference
    • Configuration

2. Core Blockchain Concepts

  • Blockchain Basics
  • Secure Proof of Stake
  • Adaptive State Sharding
  • Smart Contracts Fundamentals
  • Smart Contracts Overview
  • MultiversX Smart Contracts
  • Smart Contract API Functions
  • Smart Contract Annotations
  • Smart Contract Modules
  • Upgrading Smart Contracts

3. Development Tools and SDKs

  • SDKs and Development Kits
  • SDKs and Tools - Overview
  • Python SDK
  • Javascript SDK
  • NestJS SDK
  • Go SDK
  • Java SDK
  • C++ SDK
  • Kotlin SDK
  • Tooling and Debugging
    • Tooling Overview
    • Smart Contract Debugging
    • Rust Testing Framework
    • Memory Allocation
    • Nightly Rust

4. Building Applications

  • Developing Smart Contracts
  • Build a dApp in 15 Minutes
  • Build a Microservice for your dApp
  • Crowdfunding Smart Contract (Parts 1 & 2)
  • The Counter Smart Contract
  • Staking Smart Contract Tutorial
  • Advanced Smart Contract Features
    • Smart Contract Payments
    • Smart Contract Calls
    • Storage Mappers
    • Random Numbers in Smart Contracts

5. Transaction Management and Testing

  • Transactions and Testing
  • Signing Transactions
  • Smart Contract Call Events
  • ESDT Operations Events
  • Testing Overview
  • Running Scenarios
  • Network and Infrastructure
    • Set up a Localnet (mxpy)
    • Blockchain Operations
    • Node Operation Modes
    • Managing a Validator Node

6. Integration and Advanced Topics

  • Integrating MultiversX
  • Integrate EGLD
  • ESDT tokens integration guide
  • Host MultiversX infrastructure
  • Ad-Astra Bridge Architecture
  • Validator and Staking Management
    • Validators Overview
    • Staking v4
    • The Delegation Manager
    • Node CLI

7. Additional Resources and Support

  • FAQs and Troubleshooting
    • FAQs
    • Fix Rust Installation
    • MultiversX Tools on Multiple Platforms
  • Community and Governance
    • Governance Overview
    • Economics
    • Useful Links & Tools

Did you test the changes locally ?

  • yes
  • no

Which category (categories) does this pull request belong to?

  • document new feature
  • update documentation that is not relevant anymore
  • add examples or more information about a component
  • fix grammar issues
  • other

'technology/entities',
'technology/chronology',
'setup/installing-mxpy',
'setup/configuring-mxpy',
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • people should not be installing mxpy (yet) in "getting started"
  • configuring-mxpy is low-level detail, this isn't about "getting started".
  • is cli-overview an existing page? (oh, now I see, new page, but about what?)
  • is setup/configuration an existing page? (oh, now I see, new page, but about what?)

I'd vote to exclude these from getting started:

  • 'setup/installing-mxpy',
  • 'setup/configuring-mxpy',
  • 'setup/cli-overview',
  • 'setup/build-reference',
  • 'setup/configuration',

Instead, maybe:

  • wallet(s) - what are they & how-to
  • explorer how-to

Comment on lines +99 to +102
'integration/validator-and-staking-management/validators-overview',
'integration/validator-and-staking-management/staking-v4',
'integration/validator-and-staking-management/the-delegation-manager',
'integration/validator-and-staking-management/node-cli',
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe dedicated section for validators and staking providers?

Comment on lines +87 to +88
'transaction-management/network-and-infrastructure/node-operation-modes',
'transaction-management/network-and-infrastructure/managing-a-validator-node',
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does it belong here?

'transaction-management/esdt-operations-events',
'transaction-management/testing-overview',
'transaction-management/running-scenarios',
'transaction-management/network-and-infrastructure/localnet-setup',
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe under tooling section?

'transaction-management/signing-transactions',
'transaction-management/smart-contract-call-events',
'transaction-management/esdt-operations-events',
'transaction-management/testing-overview',
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

testing-overview is about smart contracts, I think.

Comment on lines +33 to +38
'smart-contracts/smart-contracts-overview',
'smart-contracts/multiversx-smart-contracts',
'smart-contracts/smart-contract-api-functions',
'smart-contracts/smart-contract-annotations',
'smart-contracts/smart-contract-modules',
'smart-contracts/upgrading-smart-contracts',
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be in dedicated section for smart contracts.

Comment on lines +54 to +57
'development-tools/smart-contract-debugging',
'development-tools/rust-testing-framework',
'development-tools/memory-allocation',
'development-tools/rust-nightly',
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be in the section dedicated for smart contracts.

@PhyByte
Copy link

PhyByte commented Apr 26, 2024

Hello everyone,

I want to express my appreciation for your initiative to enhance the documentation.
Over the years, as the content has expanded, it has lost some of its consistency.
I believe with the support of the builders providing valuable feedback as real users, we can significantly improve it.

My goal is to present a restructured and updated version that better suits our community’s needs. Based on discussions with the community over the past few months, I suggest the following preliminary structure as a starting point:

This proposed structure is designed to separate specifically to the distinct needs of various users within our ecosystem. It’s merely a starting point, and I look forward to integrating feedback from both the community and your team to refine it further.

Here’s a brief overview of the proposed structure:

  1. MultiversX Core Concepts
    • Introduction to MultiversX: Overview of MultiversX, its mission, and key features.
    • Architecture: Presentation of MultiversX’s architecture and network design.
    • Ecosystem: Overview of the MultiversX ecosystem, including tools, resources & key actors.
  2. Technology Deep Dive
    • Detailed Architecture: In-depth look at Multiversx architecture and network design.
    • Advanced Concepts: Detailed discussions on sharding, smart contract execution, and token standards.
    • Sovereign Chains: Core concepts & Use Cases on creating and managing sovereign chains within Multiversx.
  3. Why Build on Multiversx?
    • Advantages to build here, key advantages & features, and community resources.
    • Being a Builder on Multiversx: Explore Multiversx's mission, community, and support mechanisms.
    • Core Concepts: Dive into technical fundamentals like SPoS, state sharding, and virtual machines.
  4. Builder Journeys (Need more details)
    • DApp Creators: Comprehensive guide from DApp conceptualization to deployment and scaling.
    • Smart Contract Developers: From basic smart contract writing to advanced deployment and security practices.
  5. Validator
    • Setup and Operation: Detailed guidance on setting up and managing validator nodes.
    • Economics and Incentives: Insights into staking, rewards, and governance participation.
    • Security and Compliance: Best practices for node security and regulatory compliance.
  6. Sovereign Chains
    • Chain Architecture Design: Principles and practices for designing scalable and interoperable chains.
    • Customization and Configuration: Tailoring chain functionalities and setting up environments.
    • Integration with Main Network: Ensuring seamless communication and data consistency.
    • Security, Compliance, and Governance: Addressing security protocols, regulatory adherence, and governance models.
    • Economic Model and Incentives: Outlining the economic frameworks and validator incentives.
    • Developing and Deploying Smart Contracts: Environment setups and smart contract management.
    • Optimization and Scaling: Techniques for enhancing performance and scalability.
  7. Tools & SDKs
    • SDK: Overview and installation guide for building on Multiversx.
    • CLI: Command-line interface for interacting with Multiversx components.
    • Core Tools: Navigating and analyzing the Multiversx ecosystem: XPortal, XWallet, XExplorer, Xexchange etc....
    • Ecosystem: Present all the ressource and services of the ecosystem (Could be a collaborative section with the project teams)

I believe this structure will help to create a more coherent and user-friendly documentation experience for onboard new users, developers, and validators. It will also provide a clear path for builders to create and deploy their DApps and sovereign chains on MultiversX.

It would be great to hear your thoughts on that.

'smart-contracts/smart-contracts-overview',
'smart-contracts/multiversx-smart-contracts',
'smart-contracts/smart-contract-api-functions',
'smart-contracts/smart-contract-annotations',
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Smart contract development is not a core concept. Especially none of the mx sc scpecifics. It's not even a Rust-only thing anymore.

So we can have something on the fundamentals here, but nothing concrete, certainly no smart contract annotations/api/etc.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants