Unifying Polkadot’s developer docs: A new chapter for builder experience

The PaperMoon team, supported by a Decentralized Futures grant, is thrilled to launch the Polkadot Developer Documentation Hub—a unified resource containing the primary information for developers building on Polkadot. At this juncture, I want to reflect on how this project evolved to what it is today and, most importantly, share what comes next.

A true collaborative effort

The Polkadot Developer Documentation Hub was developed through a Decentralized Futures grant. It was a monumental project that, in the spirit of decentralization, involved many different parties working together. It is also an excellent example of how various teams can work together for a common goal that ultimately benefits Polkadot, its ecosystem, and its community. PaperMoon was one of the main drivers and coordinators of the project. Web3 Foundation (W3F) helped with general feedback, content creation and migration, and legal counsel, among other things. Distractive contributed to the general design of the landing page, general brand guidelines, messaging feedback, and support of the release process. Lastly, Parity was involved in the general development process and some coordination items.

Starting point

Among the initial scope for Papermoon’s Decentralized Futures grant was to create ecosystem-related documentation, from broader Chopsticks documentation to how to interact with Asset Hub. As we started working on our milestones, we quickly identified a much bigger problem: the fragmented state of Polkadot’s developer documentation was negatively impacting the onboarding experience.

For some time now, developers have faced several challenges with Polkadot documentation:

• Information was scattered across Substrate.io, Polkadot Wiki, GitHub, and forums.
• Much of the content was outdated or hard to find.
• Developers struggled with onboarding due to inconsistent resources.

Contrasting this with other ecosystems, where documentation is usually hosted in the same domain as the leading site, a developer building on Polkadot could easily get confused about where to start or how to find the correct information. This fragmentation created a considerable friction point, potentially driving away developers and negatively impacting SEO, among other things.

Polkadot is a sharded ecosystem, but that does not mean its documentation needs to be sharded. This realization led us to propose a significant pivot to the W3F and the DF committee: refocusing our Decentralized Futures milestones on creating the Polkadot Developer Documentation Hub. Our vision was clear: the Hub would serve as the gateway for developers to find the information they need when building on Polkadot. The data might be contained within the Hub or lead developers to an external source, such as Polkadot-SDK Rust docs. Nevertheless, developers can confidently go to the Hub; through proper storytelling, they should be able to find the resources they seek.

Finding the Right Content: Informational Architecture

We ran two separate Informational Architecture exercises to help with the Hub’s content structure. Because the content was so fragmented and partly outdated, the first exercise asked participants to create at least 15 topics or pages they would like to see in Polkadot developer documentation. In this exercise, we included 14 different key ecosystem players (W3F, Parity, PaperMoon, Distractive, Parachain Teams, Wallet developers), resulting in 154 submissions (spread across 18 categories) between contributors from different areas: 2 core developers, 2 marketing, 1 business development, 3 developer relations, 3 from ecosystem teams, 2 technical educators, and 1 product engineering. The results, summarized here, helped illustrate the areas of focus from each perspective.

With all these different cards, the second exercise asked participants to organize them into sections they would have to create, with the idea of such sections being the high-level categories of the documentation. For this exercise, we had 9 participants from various backgrounds, mostly technically minded or who understood the ecosystem well. The results, summarized here, provided at least 12 crucial sections and helped pave the way for a final informational architecture.

Through both exercises and interactions with W3F and Parity, the PaperMoon team developed a final Informational Architecture, which you can see today in the Polkadot Developer Hub. In this iteration, we’ve divided developers into four different buckets:

• Blockchain developers: Those who want to build blockchains based on the Polkadot SDK and launch them in Polkadot. They need to understand basic Polkadot concepts, configure their chain to leverage Polkadot security, access the different testing frameworks, and understand runtime upgrades, among other things.
• Smart contract developers: Those who want to build smart contract-based applications on the Polkadot ecosystem. They need to know the different paths they can choose (EVM or Wasm), the tools available, and which chain they can use (AssetHub, Acala, Astar, Moonbeam, among others).
• Infrastructure providers: Those who want to run infrastructure on top of Polkadot (validators, RPC providers). They need to know how to properly set up an RPC or validator node and the implications of being a validator, among other things.
• Tooling developers: Those who want to build a general tool for the Polkadot ecosystem (an SDK, monitoring dashboard, website). They need to know the tools they have available across the different programming languages, among other things.

The initial iteration is just the starting point. We need to start speaking to the general audience and, with enough traction and time, understand the specifics of each audience. Only then can we define fine-grained developer buckets to talk to.

Let the content migration and creation begin!

With the general Polkadot Developer Hub layout in place, we needed to start creating the pages for the content, which was a challenging task! We began by understanding what content we could migrate from either Substrate.io or Polkadot Wiki and what content would need to be created from zero.

Moving and creating the necessary content was a very intense task. We decided to update and migrate around 50 pages to the new Hub, meaning around 80+ pages would be needed for this initial iteration. This also includes the index pages, which are intermediate pages that help developers navigate to the content they are looking for.

A total of around 170 pull requests were created. Each PR was reviewed by a content team (mainly consisting of PaperMoon engineers, with help from W3F technical educators) who checked the technical accuracy and a formatting team (PaperMoon engineers) who checked consistency against the documentation standards. The process took roughly three months, combined with other tasks assigned through our grant.

In parallel, we worked on the documentation release process, landing page, and legal and brand guidelines with Distractive, setting everything up for the final release.

With everything set for release, we created an internal draft of the Developer Documentation Hub for feedback. We shared this with folks from W3F and Parity, who provided great constructive feedback on content, storytelling, and product-oriented changes.

And now, we are ready to release the first iteration of the Polkadot Developer Documentation Hub.

Next Steps

With the release of this first version of the Polkadot Developer Documentation Hub, our work is not done; it is just starting.

Immediately after launch, to ensure the Developer Documentation Hub remains a valuable resource, we will focus on the following (among other things):

• Creating a structure for a repository where all code snippets are stored and tested. This will ensure that all the relevant code snippets we show in the documentation are functional.
• Create a standard of minimum required documentation that we can pull from the GitHub repositories to ensure no content duplication requires updating with each major release. Consequently, we plan to contribute to the repositories of the tools we’ve documented to ensure that they comply with this standard
• Fine-tuning a GitHub runner that helps us keep track of new releases of products we are documenting. This helps ensure that the documentation stays up to date.
• Expanding the tutorials section to cover many other topics and provide more examples for developers.

Moreover, Polkadot's 2025 plans are very exciting, and we plan to contribute to their success by providing the right documentation for developers eager to build on Polkadot. Ethereum-compatible contracts are coming to AssetHub, and we will be working with W3F and Parity on driving a new Smart Contract narrative for Polkadot, ensuring everything is documented correctly for developers eager to start building their Smart Contracts-based applications on Polkadot.

Final Remarks

The Polkadot Developer Documentation Hub is an essential milestone for our ecosystem. It brings everything developers need into one place, making it easier to build and grow with Polkadot. This launch wouldn’t have been possible without the incredible teamwork and dedication of everyone involved.

That said, this is just the first step. A unified documentation hub only works if it stays relevant and grows with the ecosystem. If you’re building tools or projects on Polkadot, we’d love your contributions to keep improving them. Whether you add content, update information, or suggest new ideas, every bit helps.

This is open-source in the best way—by the community, for the community. Let’s work together to make the Polkadot Developer Hub the go-to resource for developers who want to create something amazing.

Check it out, share your feedback, and let’s keep building.

About Alberto Viera

Alberto Viera is the founder of PaperMoon, a developer relations as a service company that works with projects like Polkadot, Moonbeam, Tanssi, Wormhole, and Kluster.ai. Despite being a Mechanical Engineer from Venezuela with a Ph.D. in Internal Combustion Engines, you might ask yourself, “What is this guy doing here?” Alberto has been passionate about crypto since late 2013 and switched full-time to crypto in January 2020. As the saying goes, “Do what you love, and you won’t have to work a day in your life.”