Skip to main content

Why?

· 10 min read
Ross

What are the reasons for this new workflow and how is better than simply using Discourse and other tools? Lets explore some of the reasons why building a governance repo using github, docusaurus, and a few other open source tools is a no-brainer upgrade for YAM.

Strap in!​

Not all changes are for the better, and pretty much every change has trade-offs. I set out to build a governance repository because I saw that much of the information about YAM is dispersed over a number of different sites and locations, with different admin rights for each and unclear accuracy. This is something that we are going to need to tackle in the near future, so it makes sense to start thinking about it now. It is important to use the best tools for the job at hand and I believe that we can do this while using the tools that we already rely on, while adding in a few new, open source ones.

Why Github?​

  • GitHub is free. There is no recurring expense to store our documents there. And there is less risk of losing documents if payments stop because there are no payments in the first place.
  • GitHub forces open source work. Publishing to GitHub makes the published documents available to anyone who wants to view or "fork" them.
  • Github is already part of the DAO's tech stack and is a common tool among many DAOs. Learning the basics of how GitHub (and git) work is one of those things that everyone that works at a DAO should do. It is a key element in "crypto-literacy".
  • Github uses a "pull model" which allows work to be done in a fully permissionless way, with only the acceptance of that work as the point in which gatekeeping can occur. This coincides well with the Re-Org model that we are trying to instantiate at YAM.
  • Docusaurus, which is used to build the pretty front end, is open source software built with the most common front-end javascript framework, React. It is relateively simple, but if needed also can be very powerful, leveraging the full power of React. It is also the same framework as the main Yam website.
  • All of these tools use Markdown as the main way to write the text for the docs and proposals. Markdown is a simple language that allows the writer to focus on the content while ensuring legibility. It is the same text editing method that notion and discourse use, so it can translate between those media quickly and easily.

These are the quick hitting high points, but there are more things to consider, both pros and cons. Lets look at some.

Pros​

A Decentralized, Permissionless Repository for Documents​

YAM, as a decentralized organization, takes pride in the fact that anyone, anywhere can join the DAO and participate in decision making. As long as you have access to ethereum and choose to buy YAM tokens no one can stop you. In the same way, the Re-Org structure is explicitly designed so that anyone, anywhere can come propose a project to the DAO. This should be as permissionless as possible. And once the proposal and project are approved, the documents need to live somewhere that is easy for DAO voters to find and review.

Github provides a way for anyone to come see the existing documents that have been approved, fork the template files, and start working on their own proposals. They can then publicly submit their documents for review within the same platform with built in tools for that review and versioning. The YAM governance system follows a similar permissions structure, where anyone can submit proposals and votes, but the execution of those proposals has a higher bar for acceptance. The Governance and Operations Council (GSC) already operates with the mandate to execute approved proposals, and this model easily extends to merging in GitHub pull requests.

A Single Source of Truth​

The new YAM Re-Org introduces a number of new processes and documents that anyone applying for a grant, or to start a new project at YAM will need to be familiar with. Getting a new applicant up to speed on how to use each of these documents will have a learning curve and require education, good examples, and documentation. This repository, because it is built on a documentation framework, easily allows for documentation to be presented side by side with the stored documents. It also provides a clean interface to browse through contracts without having to navigate long discussion threads and discord channels.

Almost all DAOs already use GitHub as a source of truth for their code and YAM is no different. The code for the DAO smart contracts, on-chain transactions, website, and more all live on GitHub. While GitHub is not perfect, it is an industry standard and if used correctly can be quite censorship resistant. If it is good enough for our code base then it should be good enough for our grant contracts.

Looking at a specification document and wondering whether it conforms to the template? It is right there on the site. Wondering what the next step in the process is? If the docs live in the Governance Repository then the answer is just a click away. Want to see how another project wrote a document? It is right there?

(Potential) Cons​

The GitHub Learning Curve​

GitHub is scary. I get it. I was there a few months ago. I still get confused sometimes when something doesn't work. being told to go to the command line and enter something like this is not good UX:

git checkout -b temp
git reset --hard {OLDCOMMIT}
cp /var/my-site/* .
[commit changes]
git merge origin/master

But realistically, you don't need to use the command line to use GitHub and you can do everything you need for YAM governance within the website and other "normie-friendly" markdown tools. At its core, GitHub, and other development tools are simply fancy collaborative text editors.

This learning curve is only present for the grant applicants. It can all be abstracted away for the voters. We are already insisting that anyone who wants to work for YAM needs to learn and apply for a grant, which is going to be a new process for most applicants. Using github is a small part of that, and if we design the system right, it can make the process easier by making documents more accessible and the process clearer.

We will need documentation on how to set up an account, fork the repo, submit pull requests, etc. I am committed to that challenge and believe we can flatten the learning curve! And at the same time, Grant Applicants will come away with an additional skill.

Another peice of Infrastructure to Maintain​

This change adds another workflow into our process. We already have tools that we use. Why not just keep using them? I talked about some of those reasons in the "Pros" section, so I won't repeat them. Instead I want to focus on using the right tools for the job. Right now, contributors to the DAO use Discord, Discourse, Notion, and Github as our main collaboration tools, and snapshot and our website for governance. Telegram gets used a bit, but tends to be secondary. We also have our main website to maintain and the different docs, and any other websites that are created (synths, etc).

But what isn't mentioned is that the Governance Repository can reduce the amount of infrastructure overhead of the DAO. I don't expect the repo (and github in general) to replace Notion, Discord, or Discourse.

  • Discord is our living room. It is the casual space where discussions happen and news can be announced.

  • Discourse is where longer form, serious discussions happen, and I expect that it is used alongside the governance repo. Each document in the repo will have a link to the discussion thread. High level conversations of scope, intent, and viability of projects should continue to be discussed there. Detailed conversations of specific content and formatting should happen in github. Both are based on Markdown text editing so they play well together.

  • Notion is a great tool to work collaboratively, especially with databases and other rich content, and because it also uses markdown, it is relatively easy to go back and forth. But Notion is a tool for teams, and we are building out a DAO that won't have a "core team". It isn't permissionless by default, and costs a monthly fee to use. These characteristics make it less suitable as the base layer for DAO governance and information sharing, even if many contributors continue to use it.

What the Governance Repository can replace is Gitbook. Docusaurus (the underlying software the Repo is built on) serves the same purpose as gitbook, focused on documentation. Existing documentation can easily be ported to the Governance Repo to have all our important information in one place, and streamline the working process for updating it. If you can submit a grant proposal, you can update the docs.

At the same time, it lessens the burden on Discourse and Notion as the place where our documents live. Neither are fully suited to be permissionless repositories. Instead they can be freed to be the places where conversations about projects happen, and collaboration on projects happens.

Mapping out the Full DAO Stack​

I will end by laying out what tools I see the DAO using and how we do so.

  • Discord and the main YAM website together serve as the first place that interested parties go to find out more about the project. They are the starting points that lead to deeper dives into the DAO. Discord is the place for the real time discussions and collaboration. These are for everyone. Those looking for more in depth information on the DAO and how it works can be directed to the Governance Repo which would have the most up to date documentation as well as the current, pending, and completed silos.

  • YAM voters and token holders, along with Discord, would use the Governance Repo to browse Silos and brush up on how the system works. Discuss the different projects on Discourse, and then vote on Snapshot and the YAM Website (although there are some new tools like Tally that we should look at for voting).

  • Grant applications would use the Governance Repo along with GitHub to submit documents. They may wish to use a markdown editor like hackmd or Dillinger or can use their own IDE like vscode. Everything can be done on GitHub.com though. Discussions would happen on Discourse and editing and review of the documents will happen there and on GitHub. Once they have succeeded in receiving a grant, they can work in whatever software way they want, and the DAO may wish to let them use the Notion.

  • Governance Facilitatooooors would help users on Discord and Discourse, and steward proposals through the process. This would include help with writing and uploading silo applications and grant proposals. They would also be responsible for keeping the documentation up to date on the Governance Repo.

  • Finally, the infrastructure maintainoooors would keep the Governance Repo and main YAM website up to date and working (both require some skill with javascript and react), as well as make sure the github is in good working order, and merge pull requests that pass vetting and votes.

All the tools in the stack mentioned above are open source (except notion and discord, but who is counting).

I hope I have convinced you. Thank's for coming to my TED talk.