Skip to content

docs: Missing direct links to SDK repositories and empty wiki hinder developer onboarding #820

Open

Description

@Cripto5588

Problem

The README references multiple SDKs (avail-js, avail-rust, avail-go) and a "wiki page", but:

  1. The SDKs are mentioned as plain text without direct clickable links to their repositories.
  2. The referenced "wiki page" (the GitHub Wiki) is currently empty or not populated, leading to a dead end for developers seeking additional guides.

Evidence:

  • README SDK section (L12-L14): https://github.com/availproject/avail/blob/main/README.md#L12-L14
  • Wiki reference (L208): https://github.com/availproject/avail/blob/main/README.md#L208

Impact

This creates unnecessary friction for new developers:

  • Requires manual searching to locate the official SDK repositories, creating uncertainty about which ones are maintained or official.
  • The empty wiki contradicts the README's promise of finding guides for "Running Light Clients" and "Synchronization options", effectively blocking developers who need this documentation.

Suggested Fix

  • For SDKs: Add direct hyperlinks to the official repositories for avail-js, avail-rust, and avail-go.
  • For the Wiki: Either (a) populate the GitHub wiki with the minimum guides for the topics listed, or (b) remove the wiki reference and replace it with a link to existing external documentation (if available).

This is a quick, high-impact improvement that will significantly reduce onboarding time for external developers.

Activity

  1. Cripto5588 commented on May 1, 2026

    @Cripto5588
    Author

    Proposed Fix (Detailed Solution)

    @maintainers, I propose the following corrections to resolve the two identified problems. I can submit a PR with these changes if you agree.

    Fix 1: Add Direct Links to SDKs

    File: README.md
    Lines: currently around L12-L14

    Current code (plain text):

    markdown
    The following software development kits (SDKs) are available:
    
      * avail-js
      * avail-rust
      * avail-go

    Proposed code (with links):

    markdown
    The following software development kits (SDKs) are available:
    
      * [avail-js](https://github.com/availproject/avail-js)
      * [avail-rust](https://github.com/availproject/avail-rust)
      * [avail-go](https://github.com/availproject/avail-go)

    Note: If the official repositories are located under a different organization or URLs, please provide the correct addresses so I can adjust the PR accordingly.


    Fix 2: Resolve the Empty Wiki Problem

    File: README.md
    Line: currently around L208

    Current code:

    markdown
    For additional documentation check our wiki page. There you can learn how to:
    
      * Run Avail Node together with Avail Light Clients
      * Build Avail Node for different Linux flavours
      * Find out what node synchronization options are available
      * Running Avail Benchmarks

    Option A (recommended) – Remove reference and replace with real documentation:

    markdown
    For additional documentation, check our official guides:
    
      * [Running Avail Node with Light Clients](#) <!-- replace with actual link -->
      * [Building Avail Node for Different Linux Flavours](#) <!-- replace with actual link -->
      * [Node Synchronization Options](#) <!-- replace with actual link -->
      * [Running Avail Benchmarks](#) <!-- replace with actual link -->
    
    > **Note:** For complete documentation, please visit [docs.availproject.org](#) <!-- replace with actual link -->

    Option B (minimal viable) – Just remove the broken reference:

    markdown
    For additional documentation on running light clients, build options, synchronization, and benchmarks, please refer to the `/docs` directory or open an issue for specific guidance.

    Option C (if the wiki will actually be used in the future) – Keep but set correct expectations:

    markdown
    For additional documentation, check our GitHub Wiki (under construction). Topics covered will include:
    
      * Running Avail Node together with Avail Light Clients
      * Building Avail Node for different Linux flavours
      * Node synchronization options
      * Running Avail Benchmarks
    
    > **⚠️ Note:** The wiki is currently being populated. In the meantime, please refer to [EXISTING DOCS LINK] or open an issue for specific questions.

    Summary of What Should Be Done in the PR

    Item | Action | Difficulty -- | -- | -- SDKs (avail-js, -rust, -go) | Wrap names in [name](url) | Trivial Wiki link | Remove or replace with real documentation | Trivial SDK URLs | Confirm official repositories | 1 minute

    Question for Maintainers

    Which approach do you prefer for the wiki?

    • Option A – Direct links to real documentation (ideal)

    • Option B – Remove the reference and suggest /docs or issues

    • Option C – Keep wiki reference but with "under construction" warning

    Once I have the OK and the correct URLs (especially for the SDKs), I can submit the PR immediately.


    Expected impact: Less than 5 minutes of review work for maintainers, immediate friction reduction for new developers.


Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions