DevHub Implementation

[RemyLeBerre]

Summary This KR is to track the progress wrt to the new Polkadot Developer Hub. Any and all information surrounding this coordination between Papermoon <> Distractive <> Parity <> W3F should be posted here.

[kapetan3sid]

@RemyLeBerre, here is a draft of how we envision the repo structure should look like and the processes around peer review & deployment.

Repos

• We propose to have 2 repos:
  • polkadot-docs
    • This repo is hosted in Web3 Foundation GitHub org
    • Holds all the documentation
    • We will push all PRs related to documentation into this repository
    • PaperMoon will be granted Member role within this repo
  • polkadot-mkdocs
    • This repo is hosted within PaperMoon GitHib org
    • Contains the mkdocs config files, theme overrides, and css changes.
    • Contains the framework of the Polkadot documentation site
    • It is maintained by PaperMoon

Peer review

• Before merging PR in polkadot-docsrepo, we will always assign reviewers from our side.
• As for who will review our PRs from Parity/W3F side, please notify us when you decide.

Deployment process

• This is something we should discuss, but usually, we are in charge of the deployment process, and we would propose to keep it this way, considering we will be the main maintainers of the documentation
• Things we need to decide:
  • Where will the site be hosted? (Parity cloud or PaperMoon cloud)
  • Who will set up the deployment pipelines?
  • Specifics (security fail-safes, etc.)

[albertogallini]

I would suggest also to use github actions to detect from this (target) repo new releases of relevant source repos (e.g. Polkadot SDK , zombienet, subxt etc .. )

Here below the logic:

• Trigger the Workflow: Create a GitHub Action workflow in the target repository to be triggered on a schedule (e.g., hourly, daily).
• Check for New Releases: Within the workflow, use the GitHub API to check for new releases in the source repository.
• Create a Pull Request: If a new release is found, create a pull request in the target repository with relevant details.

[albertov19]

I am gathering my thoughts here after being OOO the past week.

Introduction

As you might know, PaperMoon was given a DF future grant with different work verticals, two being related to Polkadot documentation:

1. Help to create content around ecosystem tooling, processes, best practices, etc. This includes things that any ecosystem team might need outside of core Polkadot-SDK documentation. The scope here is quite broad, so we expected to tackle only some of the required documents, but it would be one of the main drivers behind it.
2. Coordinate and drive the creation of a Polkadot Developer hub that helps developers find the content they need to start building on Polkadot. IMO, Polkadot has never had good, coherent developer documentation. Everything is spread around in different Github Repos or sites like Substrate and Polkadot's Wiki, among others.

I'll focus on point 2. Being a "heterogeneously sharded" ecosystem does not mean we need sharded documentation. Polkadot is a complex system with many moving parts, so we can't expect everything to live under a single documentation site. But developers building on Polkadot deserve to learn about all the different development paths and tooling the ecosystem offers.

Content Style

There have been suggestions on how the developer documentation for Polkadot should be. One of the most recent discussions suggested that PaperMoon should contribute directly to GitHub Repos and their README instead of creating a page solely dedicated to that tool. Consequently, we can ensure that the documentation stays relevant and current.

We are against this idea and believe that to provide a good developer experience relevant to developer documentation, it should be provided on a separate page through an explicit framework about presenting documentation. This will generate coherent documentation for developers looking to build on Polkadot. Furthermore, it will help developers get used to the same content flow and cater to all sorts of developers: runtime builders, appchain developers from templates, infrastructure players, smart contract developers, and dApp developers.

A middle ground that was discussed was to ensure that GitHub Repositories have a baseline structure that can be automatically pulled into the documentation site and then work on expanding that. Consequently, you ensure that the tool's main steps are relevant, but you can add extra content on top of them.

We plan to keep the documentation relevant by using GitHub actions to notify the documentation repository of new releases of tools and SDKs. Then, teams owning that content should work on updating the documentation.

Another strategy is to ensure that this is treated as The Polkadot Documentation and that developers of such tools understand the need to go to the content repository and create a PR with the relevant changes. Moreso, if these were treasury-funded, the community could be required to consistently update the appropriate content.

Content Distribution

When PaperMoon proposed W3F to lead the development of the Polkadot Developer Hub, we knew we had to work with many different entities and contributors because the project is quite complex. It is challenging for everyone to agree on the right way to move forward. The more people involved in the decision-making process, the harder it is to advance. Therefore, I think the following might work best (this is my opinion, so I am open to suggestions).

In terms of content-ownage:

• PaperMoon will work in the Developer Hub documentation framework, informational architecture, and content coordination to be created by the different entities. In addition, PaperMoon will set standards to follow when contributing to the documentation site. To Alberto’s suggestion, we are also working on a simple tool/bot that can create GH Issues based on new releases of relevant repositories that we need to list as we work on documentation. We are also working on an AI Helper (like a RAG bot) that can help enforce standards across all contributors so that documentation seems coherent from a style/brand perspective.

• Parity can work on everything that is core Polkadot-SDK that lives in and out of the Polkadot Developer Hub. In my opinion, what should be left in the Polkadot Developer Hub should be things to start guiding developers, but not everything related to the Polkadot-SDK by itself. Nevertheless, any other contributions to content from Parity are always welcomed.

• W3F technical educators can help with Polkadot-SDK, ink!, ecosystem tooling, and “philosophical” content. They should help ensure they can provide bandwidth, as a lot of content will need to be created, updated, etc.