Aleph Docs Refactoring

General
1

Hey there!

I am intending to refactor the complete documentation of the Aleph.im project. This involves removing any links to old/deprecated docs and replacing them with pages on https://docs.aleph.im.

Besides this, our team noticed that it is hard for users to navigate and find vital information. So I took a user-story-centric approach and identified three types of community-members which have different requirements on our documentation:

  • Node Operators: It is quite difficult to run your own node without help
  • Developers: Looking for info on how to develop apps on Aleph using the SDKs, CLI and VMs
  • Investors/Researchers: People looking to learn more about aleph.im in general, its advantages and metrics & economics

This thread is for feedback on the proposed refactoring structure.

A rough refactoring has been proposed with the help of ChatGPT:

  • Overview

    • Quick Start Guide # Reuse: Overview: index.md

  • Node Operations (focused on Node Operators)

    • Node Setup and Maintenance
      • Compute Nodes # Reuse: Nodes > Compute > Installations, nodes/compute/index.md
      • Core Nodes # Reuse: Nodes > Core > Index, setups, backups
    • Node Monitoring and Management
      • Monitoring # Reuse: Nodes > Reliability > Monitoring
      • Metrics # Reuse: Nodes > Reliability > Metrics
      • Troubleshooting # Reuse: Nodes > Compute > Troubleshooting
    • Financial Aspects
      • Staking and Rewards # Reuse: Nodes > Reliability > Scores, Rewards

  • Developer Hub (focused on Developers)

    • SDKs and APIs
      • Typescript SDK # Reuse: Libraries > Typescript SDK (All pages)
      • Python SDK # Reuse: Libraries > Python SDK (All pages)
    • Development Tools
      • Aleph CLI # Reuse: Tools > Aleph Client (All pages)
      • IPFS Integration # Reuse: Tools > IPFS Pinning
      • MicroVMs # New material needed; summarize and guide using existing tutorials
    • Application Building
      • Data Handling with Aleph # Reuse: Protocol > Object Types (All subpages)
      • Multichain Solutions # Reuse: Tools > Multichain Indexer (All pages)
      • Sample Applications # Potential new content: showcase real applications

  • Understanding Aleph (focused on Curious Individuals)

    • Aleph Technology Overview
      • What is Aleph? # New high-level material needed; simplify current protocol descriptions
      • Protocol Overview # Reuse: Protocol (All subpages but more summarized)
    • Aleph Network Insights
      • Usage Statistics # New material: Create a page detailing network usage and statistics
      • Compute Resources # New material: Overview of resources available in the network
    • Aleph in Action
      • Case Studies # New material: Success stories and application cases
      • Community Projects # Reuse: Community > Projects

  • Resources

    • Troubleshooting Guides # Reuse from various troubleshooting sections
    • Glossary # New material needed unless already exists, unclear from current nav
    • API Documentation # Reuse from SDK and developer tools sections

  • Community and Support

    • Forum # New link to forums or community discussion platforms
    • How to Contribute # Reuse general contribution guidelines, new material to detail specifics
    • Contact Support # New material: Provide contact methods for support
2 Likes
2

For me, the structure feels very logical and flexible enough to scale.
The only thing I find weird is the title “Financial Aspects”. As we are a web3 project we could maybe change it to Tokenmics, token flow, …

3 Likes
3

Some user stories:

  1. As a software developer of a browser based game, I would like to host my static website on aleph.im after building it locally.
  2. As a website developer, I would like my static website to be hosted on aleph.im and updated on every git commit to main on GitHub.
  3. As a crypto bro, I bought some $ALEPH and want get moore from staking them.
  4. As a noob, I received some $ALEPH token and want to use them to host my cat photo on aleph.im
  5. As a crypto investor, I want to contribute to the network by running a Core Channel Node.
  6. As tech guy, I want to contribute to the network by running a Compute Resource Node.
  7. As a developer, I want to host some scripts on an instance using PAYG.
3 Likes
4

Maybe also a documentation on how to buy Aleph? And how to stake them?

5 Likes
5

For sure by we should add this the website.

cc @clementfd

2 Likes
6

We could expand the “Overview” section into a “Get Started” section with multiple pages:

  • Get Started
    • Introduction to Aleph.im: A brief overview of what Aleph.im is and its core value propositions.
    • Choosing Your Path: A guide to help users identify which section of the docs best suits their needs: Node Operations, Developer Hub, or Understanding Aleph.
    • Installation Quick Start: Step-by-step guides for the most common installations (CRNs and CCNs setups).
    • First Steps with the SDK: A quick setup guide for developers on how to install and start using the Typescript and Python SDKs.
    • Exploring the Aleph Network: An introductory guide for curious individuals to navigate the network, see statistics, and understand network activities.
    • Contributing to Aleph: Initial guide on how users can contribute to the community and development of Aleph.im.
2 Likes
8

Other documentations. I might find interesting to add

  1. what is metamask, why the user need it and how to install it.
  2. How to connect your metamask account into aleph-client. That user flow should also be improved, I had to do some dance in python to convert the hex value given by metamask to a bytes values, but pending that we should still document it
  3. A page on stacking
  4. Information on PAYG

(recreated a reply to fix the typo cause I couldn’t edit it)

1 Like