Virtual offsite recommendations: Waku documentaiton

Waku
1

Intro

This post outlines a recommendation to improve the Waku documentation (see also an earlier forum post about documentation issues). The topic has been researched by Jazz, Danish, and myself (Sergei), and discussed during a virtual offsite held in June 2025. What follows is a summary of these discussions.

The post contains an overview of the proposed improvements to the documentation structure, as well as a staged plan for implementing those improvements.

Slides (note: access may be restricted at the moment):

Problem statement

Waku needs to build and sustain a community, including both developers who use Waku and those who contribute to its development. Poor documentation negatively impacts retention: it discourages individuals who could become valuable users or contributors. We must support those who ask good questions and are motivated to engage.

The main issues with the current documentation are:

  • Unclear structure: users are unable to follow a coherent path through the material.

  • Fragmentation across multiple sources: documentation is scattered across the docs website, individual GitHub repositories, and other places—some of which are outdated.

  • Information is difficult to point to: there are too many sources, making it hard to direct users to authoritative resources.

  • Version ambiguity: it is not always clear which software version a document refers to.

  • Unnecessary marketing language: development documentation includes marketing-heavy language around decentralization, which distracts from technical content.

  • No opinionated learning paths: readers are overwhelmed by choices without enough context to make informed decisions.

Learnings from studied projects

Research was conducted into the documentation structure of multiple comparable projects (see References section below).

Principles

  • Examples before theory: documentation should be task-oriented and begin with hands-on examples.

  • Personas (role-based navigation): documentation should guide users based on their roles and goals. Identified personas for Waku include:

    • Application Developer (wants to integrate Waku)

    • Node Operator (wants to run a Waku node)

    • Waku Contributor (wants to contribute to Waku’s development)

  • Make documentation open for external contribution: documentation should live in a markdown-based repo that is actively maintained. Issues should be tracked and addressed systematically.

  • Interactive code examples (sandboxes/playgrounds):

    • Embed interactive code sandboxes into documentation pages, allowing users to run examples directly in the browser without setup.

    • Support multiple languages via tabs in sandbox examples.

  • Universal documentation page template: documentation pages should include standard UI elements:

    • Left-pane navigation with a table of contents

    • “Find in docs” search bar (optionally with AI assistant)

    • “Last updated” metadata showing software version

    • Dark/light theme switch

    • Feedback prompt (“Was this page helpful?”)

    • Edit/fix link (“Notice an error? Submit a fix!”) linking to the relevant GitHub repo

Proposed Waku Documentation structure

Landing page: Get Started with Waku

  • Introduce Waku with a concise overview: “Welcome to Waku! Waku is a set of protocols that enable decentralized censorship-resistant communication. You can use Waku for messaging, coordination, and other tasks.”

  • Provide a simple “hello-world” message example, embedded in an interactive sandbox.

  • Offer clear next steps based on user goals:

    • Integrate Waku into your app → link to Integrate Waku

    • Learn about Waku → link to Waku Architecture

    • Run a node → link to Run a Node

    • Contribute to Waku development → link to Contribute to Waku

Integrate Waku

  • As an application developer, you can use Waku for various use cases. Examples include using Waku for a decentralized chat app, or using Waku for multisig coordination. For additional ideas, refer to awesome-waku and ideas.waku.org.

  • Provide an SDK-based quick start guide for a typical use case, such as connecting to The Waku Network (TWN) and sending a message.

  • Offer a more detailed integration manual that includes prerequisites and installation steps.

  • Refer readers to Run a Node if they want to operate their own node, and explain the decision criteria.

Waku Architecture

Fundamental Concepts

  • Provide a conceptual overview of Waku, without diving into implementation specifics.

  • Clarify Waku’s purpose and architecture. Include diagrams and links to the Glossary.

  • Explain Waku’s relationship to IFT, and mention other IFT projects. For a broader context, link to a high-level article about network states.

Waku Software Stack

  • Clarify how components of the Waku stack relate to each other.

  • Explain the relationship between specifications, protocols, implementations, and SDKs. Specify which components are interchangeable and which are dependent on others.

  • Clarify the roles of nwaku, go-waku, and js-waku. Are these SDKs or implementations?

  • Indicate which components are needed for which purpose. For example: “To integrate Waku in your app, use an SDK…”

  • Provide an implementation feature matrix (similar to libp2p) to show which implementations support which features.

Waku Specifications

  • Explain Waku’s spec-driven development process.

  • Clarify the distinction and relationship between Waku specs and Vac specs.

  • Link to the appropriate spec documents.

Waku Research

This section is for advanced and experimental topics that are not essential for initial usage. Topics include:

  • RLN: how Waku defends against spam. Link to or reuse content from RLN docs.

  • Incentivization: WIP research on economic mechanisms, including proof-of-concept work

  • Other experimental directions and links to research papers.

Run a Node

  • Briefly explain motivations for running a Waku node.

  • Recommended method: run nwaku using Docker Compose. Provide step-by-step instructions.

    • Clearly list prerequisites, and provide a one-liner installation script (e.g., for Docker).

    • Explain the configuration model, for example: “There is a default configuration that determines mounted protocols. You can override this by providing CLI arguments or config files.”

    • Describe how to confirm that the node is running correctly.

    • Include troubleshooting advice for common issues (e.g., port forwarding, peer discovery).

  • Link to a separate page for other methods of running a node, such as:

    • Docker container without Compose

    • Building from source (link to CONTRIBUTING.md in the respective Github repository)

    • Using other implementations

Contribute to Waku

Onboard new contributors who want to improve Waku protocols.

  • “To contribute to Waku, begin by understanding the Waku architecture outlined in Waku Architecture. Contributions can include code, documentation improvements, and specification proposals. The primary Waku implementation is nwaku, written in Nim. Link to relevant Nim documentation. Additional contributions can be made to js-waku, go-waku (?), and potentially other implementations.”

  • Refer to CONTRIBUTING.md files in the respective repositories for project-specific guidelines.

FAQ

Answers to frequently asked questions, such as:

  • Does Waku have a token?

  • How does Waku differ from libp2p?

  • How does Waku differ from Matrix?

  • What is the relationship between Waku and Status?

Glossary

  • Definitions of Waku-related terminology, referenced from other parts of the documentation and cross-linked internally.

  • Use the Ethereum glossary as an example: https://ethereum.org/en/glossary/

  • Enable pop-up definitions on mouse hover, as seen on https://roadmap.vac.dev/, to allow readers to stay in context.

REST API reference

  • Link to or integrate the existing API docs: https://waku-org.github.io/waku-rest-api/

  • Provide an introduction:
    Describe the API model—there is a node which exposes CLI commands and a REST API.

  • Document the interface:

    • CLI and REST arguments

    • Flags and status codes

  • Include security best practices, e.g., warnings about exposing RPC to the internet.

  • Couple code examples tightly with API method documentation, similar to how Rust documents each method in GitBook.

  • Clearly state the version from which the documentation was generated at the top of the page.

Stages of improvement

Stage 0: Audit what we have

  • Inventory existing documentation: identify current sources (website, GitHub repos, etc).

  • Remove outdated or duplicate content. This yields immediate benefits through simplification.

    • For example: remove documentation embedded in code repositories.

  • Define content boundaries:

    • Decide what belongs on docs.waku.org versus GitHub project pages or other locations.

    • Determine whether long-form content belongs in documentation or should be standalone articles.

    • Video content is helpful but should not be part of docs.waku.org.

Stage 1: Documentation improvement MVP

  • Define and implement a new documentation structure.

    • This is not a full rewrite, but a reorganization of existing content for clarity and accessibility.

    • Improve the landing page and Get Started guide with persona-based quick starts (application developers, node operators).

  • Establish a documentation management process.

    • Make documentation updates part of the development lifecycle: when code changes, documentation is updated.

    • Assign a documentation owner (?) responsible for tracking and resolving issues in the docs repo.

    • Integrate docs into onboarding: a new core contributor should go through the docs and provide actionable feedback.

Stage 2+: future potential improvements

  • Auto-generate documentation where appropriate:

    • For example, auto-generate docs from js-waku (though it may not be REST-based).

  • Make documentation AI-friendly:

    • Create an llm.txt file that aggregates all documentation in a single markdown file for better AI accessibility (see Solana: AI tooling setup).

    • Implement Cmd + K global palette with AI-powered search.

    • Build a chat-style RAG assistant over the documentation.

    • Support hosted Model Context Protocol (MCP): e.g., when a user asks “Why do I not have any connected peers in my app?”, the AI fetches relevant status data via MCP and provides an answer.

  • Guided challenges:

    • Chapter-based learning with practical tasks of increasing complexity.

    • Examples include Speedrun Ethereum, the Rust book, and ProtoSchool.

  • Establish a Q&A platform:

    • Create or participate in an official Stack Exchange-like resource for community Q&A.

Asks

Ask for Comms Hub

Ask for Waku Dev Teams

  • Create an up-to-date CONTRIBUTING.md with clear build and test instructions.

    • For nwaku:

      • How to install the Nim development environment

      • Tooling recommendations

      • Instructions for building from source

      • How to run tests

      • Links to “good first issues”

      • Pull request guidelines and best practices

  • Add up-to-date usage examples:

    • Expand and integrate existing examples for js-waku and nwaku.

    • Use these to populate documentation with real-world usage samples.

References (Projects considered as examples)

5 Likes
2

This is a great summary! Thanks.

Would you see the “Asks” tasks to form part of Stage 1 in terms of planning? That is while building the skeleton structure and formalising docs processes, we get buy-in and contribution from CommsHub and the dev teams?

Stage 0 and Stage 1 seems to me to map very well to the FURPS we have planned for H2: pm/draft-roadmap/improve_devex_api_twn_metrics_docs.md at master · waku-org/pm · GitHub

3

Likely yes. I’d say that the asks from Waku Dev teams should definitely be in Stage 1, while the asks from Comms Hubs (interactive sandboxes) are more of a nice-to-have. Consistent up-to-date working examples, even if not in interactive sandboxes, would already be a big improvement.

Admittedly, I may be biased, as for my work I’m facing the (lack of) contributor-level documentation rather than app dev documentation, so I tend to see things like “how to build nwaku from source and run tests” as more important.

1 Like
4

We can restrict that to Logos and Status.

By components, I would aim to keep it high level: nwaku, js-waku, Waku API, RN, edge, relay, light protocols. I would not dive in details such as store, etc. as it has been a source of confusion.

Are we happy with the current section or do we want to improve it?

I would not bother too much with this in the time being. The REST API is messy and will be mis-aligned with Waku API, and we do not plan in 2025 to improve it.

Stage 0 and 1 seem good to tackle as part of [Deliverable] Review Documentation and Define Guidelines · Issue #323 · waku-org/pm · GitHub (I can see in replies that @haelius agrees :slight_smile: )

1 Like
5

Perhaps not the first priority, but there is room for improvement here too. Currently, the research page seems a bit chaotic and lacks an overarching structure. Different sub-pages operate on different levels of abstractions (high-level incentivisation ideas vs database benchmarks) without putting it all into context.