Introduction
We want to build a tribe around Waku, but we can’t do that without clear and accessible documentation. At the moment, the Waku documentation is too difficult for beginner developers. Personally, I’ve been struggling lately just running Waku, let alone contributing to it.
The nwaku documentation has been confusing for me, and I want to help improve it — both for myself and for others who come after me. I had the chance to speak with Chen and Fabio of Status in Split — many thanks to them — about the documentation for Status. There’s a lot we can learn from the Status Help pages, which are really well done.
Even though Waku targets a more advanced audience, I believe that makes clarity and structure even more important. The more cognitive load we can remove by making the docs clear and consistent, the more brainpower remains for actually understanding Waku.
We can’t build a tribe if someone like me — a full-time core contributor — struggles to build a node from source by following the instructions. That’s not a great contributor experience, and I believe there’s a lot of low-hanging fruit that would make a big difference.
Goal of this post
The goal of this post is to share my ideas and collect feedback. If there’s broad agreement, I’d be happy to help lead the effort to improve things.
At minimum, we should improve the instructions for running a node at docs.waku.org and across the nwaku repos. At maximum, we could aim to improve how we present Waku to external contributors overall — including the website, specifications, README files, and documentation.
Issues with Waku documentation
I’ve noticed several recurring issues in the current documentation:
- Curse of knowledge: The docs assume prior knowledge that readers may not have.
- Lack of structure: It often feels like I’m going in circles without a clear path.
- Inconsistent terminology: Some terms are used for close but not exactly same meanings, which is confusing.
- Too many ways to do the same thing: It’s hard to pick one path and stick to it.
- Out-of-date content: For example, the RLN smart contract address is outdated here, while the up-to-date address is here. How would a new contributor know which is correct?
Proposed steps to improve the docs
Without diving into implementation details yet, here are some high-level principles I believe we should follow when improving the documentation.
Define target audience
Our documentation should not assume that all readers are developers. We’re also writing for curious novices, node runners, and academics — people whose contributions we’d be happy to have. But they’ll only contribute if onboarding is smooth. What’s obvious to developers may not be obvious to others. A single extra sentence explaining something “obvious” could save hours of frustration.
We can think in terms of user personas:
- Alice got interested in Waku and wants to run a node.
- Bob is a new core contributor who wants to run tests.
- Charlie is an external developer who integrated Waku into his app, found a bug, and wants to submit a PR.
No matter the persona, most contributors need to understand what Waku is made of and how to run a node. That’s a universal prerequisite.
Define the goal of the docs
As a new user or potential contributor, I want two things from the documentation:
- A definition of all the moving parts of Waku and how they relate to each other.
- Instructions on how to use the software — specifically, how to run a node.
Separate political pitch from technical instructions
If I’m reading the docs, I’m already convinced decentralization is good. I don’t need reminders like “decentralized, permissionless system where anyone can run a node.” What I want are direct, technical explanations of how Waku works and how to use it.
Maintain one central entry point
There should be one clear starting point — docs.waku.org — that links to everything else. Currently we have multiple sources:
- docs.waku.org;
- READMEs in repos like
nwakuandnwaku-compose; - Operator docs in the
nwakurepo — which I only discovered by accident while drafting this post. There’s no way to get there from the mainnwakuREADME or from waku.org.
If these pages are updated, they could form a solid “Intro to Waku” section.
Provide background knowledge
It’s okay if 20% of a doc page covers things that seem “obvious.” Better to over-explain than to leave out something mundane but crucial. If we’re worried about clutter, we can hide background info under collapsible sections.
Examples of useful background knowledge:
- Config files: where they live, how overrides work
- Logging: levels, where to find logs (binary and Docker), how to read them
- How to talk to a node via REST API
- Docker basics: what it is, how to use it, what port mapping means
Waku background section
I’d love to see an introductory section — or even a separate resource — that explains what Waku consists of and how the pieces fit together. The specs are too low-level and scattered, and some are outdated or incomplete. Reading the code is too tedious. The current docs often mix “what is X” with “how to do Y.”
Possible structure for this “Waku 101” section:
- High-level overview with diagrams, like the one at https://docs.waku.org, but more detailed and technical.
- How Waku relates to blockchains; how Waku nodes compare to blockchain nodes.
- Terminology: service vs edge nodes; requests, messages, publish/push/send; connect/dial/etc.
- What currently works in practice, including RLN, memberships, etc.
- Quick start: minimal example (e.g. connect to TWN).
- “What next?”: pointers to running a node, contributing code, and so on.
This could be an MDBook like the IFT Contributors Guide, or live within docs.waku.org to avoid creating more repos.
Make expectations clear
As a reader, I want to know at each step:
- What am I doing?
- What should I expect as output or result?
- How can I verify success?
- What should I do if it doesn’t work?
The docs should clearly separate concepts (e.g. “What is RLN?”) from procedures (e.g. “How to register an RLN membership?”). Choices should be clearly presented up front, and once I’ve picked one, the docs should stick to it.
For example, when choosing how to run a node — from binary, Docker, or nwaku-compose — the pros and cons should be presented, and once I choose an option, the instructions should guide me through that path only. I shouldn’t later get nudged with comments like “oh, but the easiest way is to use nwaku-compose.”
The docs should not mix up unrelated decisions. If a certain feature isn’t available in some configuration, that should be stated clearly and early. Examples of such decisions:
- Run from binary / build from source / Docker /
nwaku-compose; - Run on a custom network / TWN;
- Run with or without RLN membership (note: without membership means relaying only, no publishing).
The docs should also distinguish between alternative options and consecutive steps. A sub-optimal example from here:
# Run the Docker Compose
docker-compose up -d`
# Run the standalone binary
./build/wakunode2
This makes it unclear that you should choose one or the other, not both.
Another example from the nwaku README that was confusing to me:
# The first `make` invocation will update all Git submodules.
# You'll run `make update` after each `git pull` in the future to keep those submodules updated.
make wakunode2
# Build with custom compilation flags. Do not use NIM_PARAMS unless you know what you are doing.
# Replace with your own flags
make wakunode2 NIMFLAGS="-d:chronicles_colors:none -d:disableMarchNative"
# Run with DNS bootstrapping
./build/wakunode2 --dns-discovery --dns-discovery-url=DNS_BOOTSTRAP_NODE_URL
# See available command line options
./build/wakunode2 --help
It’s not clear what steps are optional, which ones depend on previous ones, or which ones are mutually exclusive.
Maintain intuitive structure of each page
Every page should have a clear type and structure. There are three main types:
- Procedures: numbered lists describing how to do something — each step may link to another page;
- References: tables of options, arguments, etc;
- Concepts: definitions and explanations of key ideas.
“Every Page is Page One”
Readers often land on a page from a search result without seeing the rest of the docs. Therefore, each page should be self-contained:
- It should either contain all necessary steps or link clearly to them.
- It should offer enough context to understand what’s going on.
- It should have a consistent, predictable structure.
This approach assumes that users:
- Rarely read docs top-to-bottom;
- Want immediate answers;
- Need each page to provide the required context.
Ensure terminology consistency across code, documentation, argument naming etc.
Terminology should be consistent. One thing should have one name, and different things should have different names. Ideally, terms should come from the specs and be reflected in code, comments, CLI arguments, etc.
We should improve terminology especially around Lightpush. For example, consider this log line:
NTC 2025-04-23 11:36:32.135+02:00 Lightpush request has not been published to any peers tid=15601 file=callbacks.nim:56 msg_hash=0xd9d5c61e0d1ec5af9cd8e9411bbe673ba03fe6848155bd12ee33f857acbabd3b reason=NoPeersToPublish
ERR 2025-04-23 11:36:32.135+02:00 failed to push message
A “Lightpush request” is not published — the message is what’s published. We should clarify terms like “push vs publish” and “request vs message.” The server receives a request to publish a message, and then publishes that message. Is “push” even necessary as a term here? That needs clarification.
CLI arguments and their descriptions should also reflect consistent terminology.
Keep documentation up-to-date
Some recent developments are not reflected in the documentation. We need to think about how to maintain the docs more reliably — maybe automate part of the doc generation?
At the very least, each doc page should clearly state the version it refers to — e.g. “These docs are valid as of vX.Y.Z, released on YYYY-MM-DD.”
Preliminary conclusion
There’s a lot of room to improve how we present Waku to potential contributors — or “tribe members” — without too much effort. This post is already a bit long, so I’ll save the more concrete definitions and explanations I wish I had seen for a future post. I’ve taken quite a few notes that could feed into a glossary or other resource.
Call to action
I’d like to invite everyone to give feedback and share ideas on how we can improve the documentation and make onboarding easier for new code contributors, node operators, or simply curious readers.
-
What difficulties have you faced while working with Waku,
nwaku, or related documentation? -
What do you wish had been explained but wasn’t?
Any feedback or suggestions would be very welcome.
