How should we manage discussions on documentation?

Rick Dudley made this interesting Tweet asking about the best way to comment on a piece of governance documentation on the Community Hub. This got me thinking: how exactly should this sort of discussion happen? GitHub doesn’t have any built-in way to leave comments on documents. Before the announcement of the Collective, some of us discussed the idea of storing all governance documents on GitHub (which I’d still like to do), which would make this problem even more apparent.

To state this problem simply: how should we manage discussions and feedback on documents that live on blog posts or in GitHub?

My personal thoughts:

I don’t think this forum is the right medium for this. Presumably these documents will be changing, so any forum post that leaves feedback on the documents could become quickly outdated. It’s also very difficult to leave feedback or questions on specific lines of code. GitHub issues/discussions have the same general issue and also have the effect of somewhat polluting the repositories.

One option is to use Hypothesis, an app designed for leaving comments on websites/PDFs. Hypothesis makes it quite easy to annotate any public website and is smart enough to allow you to leave comments on specific words/lines/paragraphs. Hypothesis used to be popular in the Ethereum ecosystem a few years back (we used it all the time at Plasma Group) so people are somewhat familiar with it already. Hypothesis also allows us to create groups, which could potentially be gated based on on-chain data (e.g., “are you a delegate? you get to post in the delegates group”).

I don’t feel very strongly about this. If someone can come up with a convincing argument for why we should be using the governance forum for this, I could change my mind. I think the main benefits of the forum are: it keeps all discussion in one place, it’s more permanent than Hypothesis, and everyone is already looking at the forum anyway.


Hello there!

If we start to have discussions on documention in GitHub, what will be the purpose of this forum? We can’t have two different tools for discusssions or sharing thoughts. There has to be a way for this forum and GitHub to be sync in a way that we can all see what’s happening.


I think there are still plenty of things where a forum makes sense. For example, this very topic is well-suited to the forum. My concern is specifically around the discussion of documentation that already lives externally to this forum (like the community hub, which lives on GitHub).


Please note that this is post doesn’t represent any sort of binding decision-making process, but please do give feedback/input on this! At the moment I’m leaning towards preferring the forum simply so that we don’t have to maintain more than one communication channel (especially in these early days).


I think the idea here is that you comment on the medium that it is delivered. So if something is delivered on the forum you comment there and if something is delivered in github you have the discussion there.

Trick is being careful about where you start the discussion.

1 Like