Some people have mentioned on the Discord that a central repository of specs/documentation would probably be pretty useful, since current information about this project is currently scattered across multiple pages on the Web5 site and various RFC’s that the W3C has uploaded to GitHub.
I feel like a wiki would be the ideal format both for surface-level explanations of what exactly Web5 is (for the non-technical/curious journalists/potential users, etc.) and also would be the quickest way to scaffold robust documentation for the official implementations, especially as they evolve. (Arch, for example, started a wiki to keep track of installation tips and it’s now one of the gold standards for Linux documentation.)
I’d be happy to help host; I have some experience with MediaWiki, which is what they use to host Wikipedia. It’s a much better way to keep track of accrued knowledge than having to grep through forums or Discord archives, plus it’s really cool to say that your project has an active wiki. We could host it on
Anyone have any thoughts on this?
Love the initiative. Docs and examples are going to be the things most influential in driving us forward!
A little about what’s coming - and I’m curious how you (and others!) think this may help along the lines you’re mentioning.
Our developer site at developer.tbd.website is equipped to pull Markdown content from external repos. We set it up this way so we’d always have the option of giving both project leads and community members a place to propose docs to be surfaced on the site, all backed by PRs just as a code contribution is.
As we build out the content program for Web5, does it seem like adding material in Markdown and publishing on the developer site in this fashion gets the job done? Something I like about this model: anyone can propose docs/examples contributions, and we still get verification from project leads via the PRs before publishing.
Yeah, I like that model a lot! It’s actually the thing that got me thinking about expanding on that model of community-created documentation.
I suggested a wiki because it addresses what I see as a few big scaling pain points of the mirrored Markdown model:
- Right now, the vision for Web5 seems to be a set of interoperable standards. While you don’t have to use all of the components, easy interoperability and common branding are a big intention; we want people to see both DWN’s and DID’s as components of a friendly modular stack, for example. That’s might be hard to do if all the standards are conceptually “silo-ed” into different “project” pages and have a hard time linking to each other.
- The mirroring system means that each page will contain the project’s README file, which will give a high-level overview of what the project does, some simple installation instructions, a guide to contributions, etc. From my open source experience, self-documenting repositories quickly become undocumented repositories, which can be the kiss of death for contributions. The kind of introduction to a project found in a README is often very different from the technical documentation developers need. (Likewise, the
projects.tbd.website domain implies high level descriptions of the projects and some guides to getting started, not in-depth documentation, which may lead to some confusion.)
- The process of forking a repo and opening a pull request adds a lot of friction for someone who just wants to add one or two changes to a project, especially if that someone is a user who doesn’t really code and just wants to take a few seconds to add something to the documentation. This has been and remains my single biggest gripe with GitHub’s user flow for, like, a decade now and it still mystifies me that there isn’t an easier way to do it, but the friction it creates really does hit docs the worst.
- Lastly, and may sound like a personal gripe, GitHub is a centralized service that requires strong permanent credentials to contribute to any of its content. Obviously we need something like that for building the product itself, but this is supposed to be a project that makes it easier for people to participate without those kind of gatekeepers. It’ll always be easier for someone to jump in on a wiki or forum than by submitting a pull request to a GitHub repository. If we’re worried about vandalism, there are absolutely ways like mod-queues to make sure everything gets run past a community member before it goes live.
Obviously a GitHub link would still be front and center on every page of this wiki, which would take users to the official README’s, formatted by GitHub, plus the
projects.tbd.website domain would still mirror them; this is hardly an either-or situation.
There are, of course, other solutions, too; I know
docs repos are common, and there’s stuff like GitBook that can format them into nicely formatted documentation that can live on
docs.tbd.website or something. (You’re still relying on centralized services like github, of course, but it’s a more robust method of hosting documentation.)
Sorry for the text-dump! Realized I had more to say than I thought!
I really like the idea of a wiki. A community driven knowledge-base would be a huge value to everyone joining the web5 space.
Really compelling arguments, ag4536.
Before I get to those - a minor correction on the Markdown model for developer.tbd.website so we’re on the same page there. We don’t need to “mirror” the repository structure on the developer site. It’s one of the nice parts about that design; we can surface pages on the site pulled from Markdown files anywhere in our repos, so we can compose things together in ways that make sense for readers, while leaving the authoring environments in a way that makes sense for code modularity. It’s good of you to call out that these don’t always match.
OK, the Wiki:
Thinking on it more, I believe there’s room for both a publishing model on the developer site for docs as well as a community-driven Wiki. There are some prereqs I’d want to stand up before setting this up. And those depend on our community moderation program that we’re setting up.
So consider me convinced - now a matter of timing and scheduling. And I’ll post back here soon calling for parties interested in community moderation!
Sounds great! Looking forward to it!
Filed so we don’t lose track of this:
I think I like the idea. I’m actually one of the curious ones. Documentation of knowledge is important. That’s what brought me here.
I’m interested in creating educational content for Web5