RFC: Migrate Radix Developer Documentation to RADIX.wiki

Governance Radix Community DAO
1

TLDR: The current Radix developer docs are fragmented across 6+ domains. I’ve run 8 workshops onboarding developers to Radix and maintained RADIX.wiki since 2022. I’m offering to host all documentation for free on a Wikipedia-style platform where anyone can contribute and earn points for keeping it current.

The site is live at radix.wiki

Introduction

The existing developer documentation for Radix is fragmented across docs.radixdlt.com, developers.radixdlt.com, academy.radixdlt.com, learn.radixdlt.com, radix-engine-docs.radixdlt.com, radix-core-api.redoc.ly and Github. This architecture and the tendency of documentation to become quickly outdated has made developer onboarding much less efficient than it could have been.

My conviction is that developers are the primary customers of digital ledgers so in 2024 I organized the Radix Wiki Hackathon (radixdlt.com/blog/the-radix-wiki-hackathon) and have run eight ‘DappInADay’ (radix.wiki/contents/history) workshops at London universities since then.

In planning those events I found it useful to create a Developer Resources (radix.wiki/contents/resources/radix-developer-resources) page on RADIX.wiki that the students could use as a reference in preparation for and during the events.

Now, with the Radix Foundation dissolving, there is an opportunity to rationalize and improve the entire documentation and onboarding flow for the hordes of developers we’re expecting to descent on Xi’an. My proposal is to host that documentation on RADIX.wiki - a site that I’ve maintained since 2022.

I built the wiki around July 2022 and received a Dandelion grant (radixdlt.com/blog/dandelions-program-update) to develop it in October of that year. My main rationale was that the only proven model for maintaining knowledge bases of this magnitude is distributed contribution with low friction, i.e. the Wikipedia approach. A comprehensive, up-to-date documentation of the Radix ecosystem can only be successful at scale with a Wikipedia-style knowledge base that anyone could contribute to.

Not being a developer, I wasn’t able to develop the site as a Radix-native app, but with the advancements in AI I’ve finally been able to build what I originally envisioned. The staging site is radix-wiki.vercel.app and once there’s parity I’ll move it to RADIX.wiki.

I’ve started to sketch out the developer docs here: radix.wiki/developers

The Offer

I’ll host the documentation indefinitely, at no cost to the community. I’ve been following Radix since 2017 and I’m building caper.network on Radix so I’m not going anywhere. I also have a vision to host more workshops and build an ETH Global / Superteam for Radix so it’s in my interest to make sure the documentation is accurate and effective.

RADIX.wiki already has the infrastructure, the domain, and a track record of continuous operation. There are no hosting fees or grants needed. The documentation simply needs a home and community buy-in.

The question of redirects from the existing documentation is up for debate but I’d argue that the current structure is such a mess that it would be better to add a blanket redirect rather than invest a lot of time and effort to preserve individual links.

Functionality

The wiki platform is designed to be as decentralized as possible. Users connect their Radix wallet to create and edit wiki pages organized in a hierarchical tag system. The app features a block-based content editor with support for rich text, code blocks with syntax highlighting, tables, tabs, YouTube/iframe embeds, and image uploads. Pages support revision history, threaded discussions, and user reputation scoring. Certain actions require minimum XRD token balances, creating an quasi-economic moderation system. Community members automatically get personal profile pages, and the platform tracks contribution statistics including pages created, edits made, and account age. Eventually I’ll work out a way of backing everything up to the Radix ledger or even hosting it on an RNS domain.

Postscript - Governance & Long Term

I’ve always planned on governing the wiki as a DAO on Caper with its own governance token. I also plan to honor the idea I sketched out here: t.me/EasyMoonDiscussion/5142, meaning that $EMOON will be exchangeable for the new governance token.

Contributors currently earn points for maintaining and improving the documentation. These points recognize effort and create accountability, which aligns incentives: people who use the documentation have a direct path to improving it and being recognized for that work.

The long-term objective of the DAO will be to raise its own funding on the Caper platform and thereafter run as a profitable entity so that it never has to seek external funding. A future Radix Global is part of that vision but any future plans will be decided by the DAO members and is beyond the scope of this immediate proposal.

Why Not Github?

So many reasons…

  1. Not Radix native.

  2. Not suitable for illustrated or interactive tutorials.

  3. Unsuitable for beginners.

  4. Even Dan Robinson (x.com/danrobinson/status/2006684676291965094) finds it too complicated.

  5. Horrible UIX.

  6. Limited embedding.

  7. Can’t be governed as a DAO.

What We Need From the Community

  1. Consensus that community-maintained documentation is preferable to abandoned official documentation.

  2. Content access to existing documentation sources (or permission to scrape/migrate).

  3. Contributors willing to help with the initial migration and ongoing maintenance.

Conclusion

Poor documentation does more harm than good.

RADIX.wiki was created for this situation. The infrastructure exists. The commitment exists. The model is proven across thousands of successful wikis.

Let’s give Radix documentation a permanent, community-owned home.

15 Likes
2

These is something where i totally agree , radix doc currently sucks , and the way to find things is really worse , i like a lot your platform to put the doc.

3 Likes
3

I’m ok with it, I’m only worried that you become a single point of failure.

You should make it possible for someone else to retrieve a full backup of the whole site

4 Likes
4

100%. Ideally the site will back up to the ledger and the dream scenario would be to host it on RNS.

4 Likes
5

I welcome this RFC,especially at no cost, it is a no brainer to me. I’m not a dev, but always interested in reading technical doc and examples. Radix docs are too fragmented and outdated. This is something the community can “easily” take over and improve.

3 Likes
6

I support, in principle, the use of a versatile platform to hold knowledge, and one that’s open enough so that we can have a decent collaborative method of creating and improving its content.

Problem is that having the tool is the easy part - how to make sure the information is accurate and verified is the hard one. Your proposal is not enough for this second part, imho.

Also, I understand you’re the owner of Radix.wiki … and imho this should be hosted in a domain that’s under the DAO’s control, regardless of having you or anyone else as the operator/stewart.

Would you relinquish the domain to the DAO? Would you be willing to operate it under a DAO-controlled domain?

If this is to contain verified accurate information, we’ll def need to have editorial and verification, else everyone just posts whatever it feels like and if not countered, others will believe it to be accurate.
As you said, having bad/incorrect/outdated info is worst than not having any.

1 Like
7

Thanks for your comments @projectShift. Here are my thoughts:

With all of the Foundation and RDX resources behind them, the current docs are a mess and full of inaccuracies so I’ll reiterate the core thesis of my proposal, which is that a permissionless wiki is the only proven way of managing such a large and dynamic knowledge base. Encyclopedia Britannica might be slightly more accurate than Wikipedia, but to be honest I doubt it, especially in fast-moving domains, and certainly not by enough to justify its slow publishing schedule and high production costs. We can do it without having to directly pay editors.

As mentioned, editing has token gating that can protect sensitive pages without permissioned locking (although that’s also possible). Having a governance token solves the alignment: DAO members are incentivized to contribute and keep the information accurate. IQwiki runs a similar system but it can be implemented much more elegantly on Radix.

On the domain name, I want it eventually to be an XRD domain in the DAO treasury but prior to that I’m not sure how the DAO would control the domain as ultimately someone has to have the registrar username and password. But in principle, yes, the DAO should control it.

8

(I put this response together with chatgpt, I had previously brainstormed and this idea for many many hours, but I never went anywhere with it because of a lack of technical knowhow. If people see any value in this idea, let me know and I can share some more of my thoughts. I also have not yet claimed the HOUR token ticker, so please don’t create it unless you have the intention of implementing this system.)

Your highlights something broader for me: beyond documentation, Radix is facing an organisational challenge — how decentralised work gets coordinated, rewarded, and legitimised over time.

I wanted to share a very early-stage concept I’ve been thinking about, in case it’s useful here. I don’t have the technical knowledge to know whether this is feasible — this is very much broad strokes, not a deployable system.

The idea is something I’ve been calling the HOUR Network / HOUR DAO.

At a high level:

Contributions are measured in time rather than speculative value.

For every ~1 hour of work (loosely estimated), a contributor receives 1 HOUR token.

HOUR would only ever be created through verified work, or possibly via explicit value locked into the system — no free issuance.

The aim is decentralised coordination that rewards real effort and lowers barriers to participation.

The “hour” wouldn’t be precise — it would be based on good-faith estimates and social verification.

Early on, something like this could run invite-only for trusted community members.

Conceptually, contributions would be logged via a forum-style platform connected to Radix (RADIX.wiki already feels adjacent), and each contribution would fall under one of four aims:

Task division

Task allocation

Reward provision

Information provision (documentation fits naturally here)

To discourage gaming, contributors could place a small deposit proportional to hours claimed, forfeited if work is dishonest. Legitimate contributions receive HOUR, with everything transparent on-chain.

I see this less as “governing Radix” and more as a coordination substrate that could sit alongside the network — helping organise ecosystem work (like docs), reward contributors, and create a pathway from participation → value → governance.

Not a finished system — just a conceptual starting point prompted by your post.

9

Generally the idea of gathering together all knowledge and docs is good, but I’m afraid the wiki platform you’re proposing is not gonna make it. I’m not a programmer per se, but I would expect something more established and polished in terms of documentation.

In my opinion we should use a CMS or Docs platform, that has some track record, maybe even open source so we can self host or move it in case on force majeur. Plus these platforms have multi-user management, admins, etc. So the council should be able to delegate people to update.

Currently Radix uses This platform if I’m not Wrong: Build Your World-Class Documentation With Document360

I know Gitbook has also a FREE tier specially for communities or non-profits, that is fully free. They add some AD banner in the corner, but it’s free.

I’m sure that there are more, but generally I think we have to reduce our risk by using custom platforms. Use the standard and keep it simple.

And to add to this, top 20 blockchains use:

Docusaurus —- (open source - Solana, Cardano, Algorand, Lido, Chainlink)

GitBook. —- (Base (Coinbase), Polygon (some sub-docs), Uniswap, PancakeSwap)

Next.js / Custom React. —- (Ethereum.org (customized Next.js), Stripe (Crypto).)

mdBook: A Rust-based tool that is incredibly fast and renders Markdown into a simple, searchable book format. It’s the “gold standard” for Rust-heavy ecosystems. —- (Users: Polkadot, Cosmos, Near, Rust (the language itself).)

Docusaurus looks pretty polished imo and is maintained by Meta. We can self host.

2 Likes
10

Those services are often just wrappers for JS libraries. For example, Docusaurus uses Prism whereas we use Shiki, but in bundling there are often tradeoffs, especially with auth and customization that can highlight Radix’s unique benefits. The advantage of this wiki is that we can easily swap out libraries if a better one comes along, whereas wrappers will tie us in.

Did you log in and try it out? Would be good to hear how it could be improved.

11

Thanks but … my issue is that we need to have a way to make sure the information is accurate.

I’m not arguing it needs to be paid or not, that’s not the point. Just that it needs to exist.

For that we need authority in the sense that someone that can attest the information to be accurate will verify it and “seal it” as so.

Else, since anyone can insert content, if no actual verification is done, the information is not authoritative for the domain it pertains.

When talking about documentation like this, we need to ensure that authoritative status.

That’s what I’m saying that’s missing from your proposal - having a DAO or a token or wallet-identity does not solve that at all.

12

In software, accuracy is a moving target because libraries are updated all the time, breaking changes are introduced, etc, so the ‘authorities’ in this case are the developers actually using the docs to build things. This has been the frustration in running the DappInADay workshops: the docs had been ‘sealed’ by RDX but they hadn’t kept up with the changes so there were lots of breakages. Users would report them, but then faced a permissioned bottleneck to implement a fix. We had senior engineers at the workshops who were qualified to change the docs there and then, but they didn’t have the ability to do so. Enabling token-gated, immediate changes has significant compounding benefits to make sure that no bug is ever left untreated. I’ve seen the benefit that this kind of system will have.

13

I wanna add something about the UI, Radix.Wiki has a different UI than FND docs, would you plan to use the FND UI or not ?

I mean, this for example is quite simple to read, it’s quite simple text

14

UI updated! radix-wiki.vercel.app

15

that is great and i also managed to add a block to a web page. this is quite different from the current main documentation but it could be a great point to start with. connected wallet could also be gated by mintind an ‘Editor Badge’ if want to be sure about what info is added and if that comes from an authoritative source

1 Like
16

That’s a great idea. Glad you could add a block successfully!

17

I agree here—although the docs seem dusty and boring, we actually have a huge ecosystem that needs to be documented. We should stick to a proven system/CMS/SaaS (whatever it may be) that a) won’t end up as a single point of failure and b) allows us to keep the docs up to date while still supporting proven version control, roles, etc. GitBook looks not bad, or Docusaurus. I guess we could even build our own with Payload, etc., which would allow for custom features we might want to have for Radix.

18

accurete & verified versus decentralized & community is the challenge :confused:

19

In general i like the idea, and i think there may be some growing pains and risks, but the payoff is the path to true decentralization.

20

We need to get this done.

Little bump here. I’ll have to see if I can get efforts started to move the docs.

2 Likes