3rd Party Documentation (and incentives for community contributions)

[burrrata]

Hack.Aragon is cool, but it doesn’t have all the answers. The #dev-help channel on Rocket is also cool, but sometimes it takes 24-48 hours to get an answer and/or questions get lost in the shuffle. As such, the best way to solve Aragon related dev problems is to refer to your own notes and/or hit up other people in the community to see how they did something. Most major platforms have acknowledged this and rolled out a community wiki for people to share their process for getting stuff to work (for example ArchWiki). We also have hack.aragon, but it feels a little too “official” for people to just post a “here’s how it works on my machine” doc. There’s also the Aragon Wiki, but afaik know no one uses it. Looking at the commit history it’s maintained by A1 who pays their team to do so. That’s great, but it doesn’t scale.

This makes me thing that there’s an incentives problem regarding Aragon community contributions. It would be great we had a meaningful way to encourage community members to contribute to the wiki. Perhaps some sort of ANT reward system for community contributions could help make this happen vs relying on altruism or the A1 team. The goal being to A) recognize community contributions in a meaningful way, and B) align incentives of community members to encourage participation in ANVs (atm participation is painfully low).

TL;DR: Started this thread as a discussion to support 3rd party docs, but then realized that we have a great wiki. Problem is, no one uses it. There aren’t any incentives for people to contribute to the Aragon community unless you’re crazy, a whale, or it’s part of a flock team’s KPIs. This needs to change if we’re going to evolve and scale as a community

[Aaron]

+1 to everything here! Just getting set up to use the cli was a struggle for me. The plethora of tooling is overwhelming and I often post to the dev channel with my specific issues but the format is not conducive to finding answers before asking questions.

As such, the best way to solve Aragon related dev problems is to refer to your own notes and/or hit up other people in the community to see how they did something

We also have hack.aragon, but it feels a little too “official” for people to just post a “here’s how it works on my machine” doc

I have written up a few guides to issues that i have found difficult to solve but have no place to share them. I imagine many others have too.

There’s also the Aragon Wiki, but afaik know no one uses it. Looking at the commit history it’s maintained by A1 who pays their team to do so. That’s great, but it doesn’t scale.

This is a great idea, but I think it should be limited to this, we should also open a new forum category. Most other projects use the forum for this function anyway. There is less friction (no need for PRs) and if someone needs additional help they can just ask in the thread. we could then archive articles / guides in the wiki making it a much more useful

It would be great we had a meaningful way to encourage community members to contribute to the wiki. Perhaps some sort of ANT reward system for community contributions could help make this happen vs relying on altruism or the A1 team.

This is also a great idea. One of the goals of coop was to provide a route for meaningfull contribution to community members. Maybe we could create a new DAO similar to CFDAO to manage small ANT rewards.

Definitely an idea i think we should explore a bit more.

[Mouyou]

perhaps colony.io could be a place for inspiration. They have a reward mechanism. perhaps someting for aragon developers starting with a simple reward token people can earn and then they can make a proposal for backing this tokens with ANTs (bonding curve) so every person can exchange those tokens to ANT and vice versa?

[light]

Re: “where to post community-written dev guides”. I think hack.aragon.org would be a great place. While you are right that what is there now is intended to be more “official” documentation I personally think it would be great to have community-written guides there, either denoted as such and weaved into the existing structure, or in their own “Community-written guides” section.

Re: rewarding documentation contributors. I think the Community Funding DAO could be a good source of funds for this in the short term. Either community guide authors can request funds directly, or a person/ group of people can volunteer to be a “docs bounty admin” who makes a bulk request for funds and then is responsible for assessing and paying out docs bounties to people who contribute guides. Autark’s tools could be useful here, and I know @gabi and @danielconstantin have already started experimenting with bounties to help with Aragon Mesh work.

[light]

This is a great idea, but I think it should be limited to this, we should also open a new forum category.

The forum category names are quite out of date as-is. I think the “Technical” section was intended for dev related topics, but we could either rename or create a new category specifically for “Dev Help” if there is demand for it.

[burrrata]

Where?

I have written up a few guides to issues that i have found difficult to solve but have no place to share them. I imagine many others have too.

I’ve used them. They’re good and they work. They should be published.

This is a great idea, but I think it should be limited to this, we should also open a new forum category. Most other projects use the forum for this function anyway.

The Rust community does this with their forum, but their main focus is the programming language itself. Aragon is much more dynamic, and as such the forum represents a much more dynamic set of interests. Also, having #dev-help, the wiki, hack.aragon, and the forum for technical related things might be a bit much. Personally I want everything in one place so that I can be as lazy as possible, quickly find answers/resources, and get stuff done. I don’t want to have to cross reference multiple locations every time I have a question.

hack.aragon.org would be a great place. While you are right that what is there now is intended to be more “official” documentation I personally think it would be great to have community-written guides there, either denoted as such and weaved into the existing structure, or in their own “Community-written guides” section.

A “Community written guides” section would totally work. It would make it clear that community contributions are welcome and encouraged. That being said, the wiki also has a development section. Seems kind of redundant? There should be 1 place people go to for information about building/using Aragon DAOs. Simple, easy to share, easy to contribute to, easy to manage.

Incentives

perhaps colony.io could be a place for inspiration.

Yup! Already talking to them about creating an Aragon app that could be integrated into DAOs. Their thinking was that the Agent app could be the founder of a Colony, and then the DAO could manage it that way. Details TBD and it would require some integrations into their wallet infrastructure.

Also talking to the SourceCred team about integrating that system into Aragon DAOs.SourceCred essentially creates a “contribution graph” of people who contribute to a project and then dispenses tokens accordingly. This could help automate contributions to the forum or PRs to various repos. It’s in super early beta, but the da0 is looking at building that into their Aragon DAO as well

Autark’s tools could be useful here

Autark has awesome apps that would be super useful here, but they won’t be ready for mainnet for another few months

I think the Community Funding DAO could be a good source of funds for this in the short term. Either community guide authors can request funds directly, or a person/ group of people can volunteer to be a “docs bounty admin” who makes a bulk request for funds and then is responsible for assessing and paying out docs bounties to people who contribute guides.

This seems like the most promising immediate solution, but first there would have to be documentation explaining the documentation bounties/rewards process lol! As is, navigating the community funding DAO is confusing unless you’re already engaged in the forum on a daily basis and were around when it was created. The UX needs to be improved greatly. Perhaps we should create an updated post explaining what the CFDAO is, how it works, and how to contribute. Then that could be stickied in a “CFDAO category” just for CFDAO proposals/discussions.

Then there could be a non sticked post in that category explaining the community docs/tutorials process and expected rewards one could earn for contributing. This could be in the style of the bug bounties: not as specific as bounties on the Projects app, but not as vague as allocations; something that gives the reader a general idea of what they can expect and leaves details up to the bounty manager or community

[lkngtn]

I’m currently looking into the creation of a bridge between https://sourcecred.io and Aragon. The idea being that you would have a node which computes sourcecred “cred” based on discourse posts and/or github contributions, and then either mints reputation directly or requests the approval of new reputation based on a vote. I’m fairly optimistic this is something that could be created fairly quickly. The the cred would be computed and then distributed using an approach that is similar to a merkle airdrop.

I think it would make a lot of sense to experiment with rewarding contributions to wiki.aragon.org and hack.aragon.org repos with reputation tokens based on “cred”, and perhaps allocate some amount of funds which could be distributed to those reputation holders using 1Hive’s redemptions app.

[light]

. That being said, the wiki also has a development section. Seems kind of redundant? There should be 1 place people go to for information about building/using Aragon DAOs. Simple, easy to share, easy to contribute to, easy to manage.

You’re completely right. We’re in the middle of a big Aragon Wiki re-design/ re-organization and have planned to remove the development section.

[1] https://github.com/aragon/aragon-wiki/pull/499
[2] https://github.com/aragon/aragon-wiki/pull/480

Then that could be stickied in a “CFDAO category” just for CFDAO proposals/discussions.

This is another thing I’ve been thinking about and mentioned in another thread: in conjunction with the wiki re-organization I am also working on a forum re-organization to bring the forum up to date with how people are actually using the forum as the current structure is quite out of date and hasn’t changed much since back when the forum was originally intended just for research.

That said I think the original CFDAO announcement post is actually quite straightforward for explaining how to participate. I think @anteater struck a good balance between making the post detailed but also low-barrier to participation. What could improve is, as you say, making it more visible. Giving the CFDAO its own section / subsection in the forum would be helpful here.

[burrrata]

Awesome!

Looking forward to the wiki/hack re-organization. Are you thinking to have a “community contributions /3rd party docs” section in each of the main sections (aragonPM, aragonOS, aragonCLI, etc…), or to just have a single “community contributions” section where people can just add anything as long as it’s technically correct? Also, it would be great if there was an “Apps” section that had info and documentation (overview and install/user guides) on every Aragon app in the app store.

The original CFDAO post is good, but it’s hard to find. Having a dedicated CFDAO tag and category would help greatly with this.

[light]

Looking forward to the wiki/hack re-organization. Are you thinking to have a “community contributions /3rd party docs” section in each of the main sections (aragonPM, aragonOS, aragonCLI, etc…), or to just have a single “community contributions” section where people can just add anything as long as it’s technically correct?

My work is exclusively on the Aragon Wiki at wiki.aragon.org. I will not be touching the hack.aragon.org site.

Also, it would be great if there was an “Apps” section that had info and documentation (overview and install/user guides) on every Aragon app in the app store.

I agree it’d be nice if docs for each app were easy to find. Right now frontend app documentation for the “core” apps that are shipped with each default template are located at help.aragon.org, but there is not a canonical place to find documentation for other apps in the App Center. This has been discussed before during the All Devs calls for example but we haven’t come to any final conclusion about where non-“core” app docs should live. At the very least, we could add a docs section to the App Center listing page and require all submissions to have a link to documentation of the app. Right now, if there is any documentation at all, it usually lives in the GitHub repo for the app in question.

[burrrata]

My work is exclusively on the Aragon Wiki at wiki.aragon.org. I will not be touching the hack.aragon.org site.

Well if we’re removing the developers section on the wiki, there where is that information going? You’re not just removing useful information right?

Also, IF the place for community documentation is hack.aragon and NOT the wiki, then who else needs to be involved in this conversation to make that happen? Who’s the “manager” for hack.aragon?

At the very least, we could add a docs section to the App Center listing page and require all submissions to have a link to documentation of the app.

That seems more than reasonable. I’m astonished that it’s not a requirement for teams that get funded. There’s no point in building amazing applications if no one can use them lol

[light]

Well if we’re removing the developers section on the wiki, there where is that information going? You’re not just removing useful information right?

Most of it is getting moved to the archive section because it’s so far out of date it is actually not that useful. Nonetheless I am an information hoarder so it will be kept online, just moved to a less conspicuous location (the archives).

Also, IF the place for community documentation is hack.aragon and NOT the wiki, then who else needs to be involved in this conversation to make that happen? Who’s the “manager” for hack.aragon?

@luis or @gabi would know better than I do about this.

That seems more than reasonable. I’m astonished that it’s not a requirement for teams that get funded. There’s no point in building amazing applications if no one can use them lol

The default apps are all well documented, and in fact the documentation is accessible directly in each app by clicking the question mark in the corner. The work in progress apps are not so well documented, which is to be expected since they are… well… works in progress, and it’d be a waste of time to fully document something that is not yet in a finalized state. If there’s a specific app that you’d like to see documented I encourage you to reach out to the dev directly and make your request to them. In the mean time, it would be worth tracking this idea about putting documentation directly in the App Center listing as an issue in the Aragon client repo. I have created this issue here.

[burrrata]

The default apps are all well documented, and in fact the documentation is accessible directly in each app by clicking the question mark in the corner.

Yes! And this is why I’m so adamant about documentation and dev ux, because I know what’s possible and want to see best practices established across the ecosystem

The work in progress apps are not so well documented, which is to be expected since they are… well… works in progress, and it’d be a waste of time to fully document something that is not yet in a finalized state.

Obviously. This is why I started this thread: community documentation for more obscure edge cases or things in development would greatly enhance the dev ux for early adopters and hackers

[light]

Obviously. This is why I started this thread: community documentation for more obscure edge cases or things in development would greatly enhance the dev ux for early adopters and hackers

I see what you’re saying. I think you could make a PR to the repos of the specific apps you’d like to see documented and drop a markdown file there, as a stopgap until we have established how/if we want to put “community” docs in the hack.aragon.org site.

[burrrata]

I see what you’re saying. I think you could make a PR to the repos of the specific apps you’d like to see documented and drop a markdown file there, as a stopgap until we have established how/if we want to put “community” docs in the hack.aragon.org site.

Yes, I could do lots of things. I’m busy af tho. There’s no incentive for me to say no to other things in order to contribute altruistically to Aragon community documentation. Thus the other half of this conversation: incentives for community contributions.

[light]

I’m busy too yet I contribute documentation to open source projects quite often with no expectation of remuneration. If you want documentation ahead of a developer’s planned schedule, you should expect to have to do it yourself. If you want payment for doing it, you could put a donation address in the docs or request funds from the community up front before writing the docs (like crowdfunding). All of this is possible today with no extra tooling necessary. In other words: what are you waiting for?

[burrrata]

I’m busy too yet I contribute documentation to open source projects quite often with no expectation of remuneration.

Good for you. The whole point of blockchains and tokens is that cryptoeconomic mechanisms align incentives in a positive sum way for all parties involved. This is ARAGON. We are creating DAOs that allow communities to manage governance and fundraising in ways that are BETTER than before.

what are you waiting for?

I’m waiting for a clear and thoughtful incentive mechanism that shows that the Aragon community gives a shit about it’s non core contributors.Even just a signal in that direction would be enough. As is, just saying “do it” feels like you don’t care, don’t value community contributions, and don’t understand incentives around real world constraints like the opportunity cost of time.

[Aaron]

If you want payment for doing it, you could put a donation address in the docs or request funds from the community upfront before writing the docs

Personally, I find it uncomfortable asking for money and would never put ‘donation’ link anywhere . Paid or not I always contribute as much as I can because I love the project and am fully signed up to the vision.

However, I do see merit in having a system that rewards community contribution in ANT

• rewarding contributors with small amounts would increase community participation.
• it would give contributors a feeling of ownership, recognition and appreciation
• I also think it would boost the participation in the AGPs which is a metric I think we should be optimising for (probably not by much but it’s a step in the right direction)

Also experimenting with DAO initiatives like seems like something we should be supporting, especially when the cost very little and potentially have a big upside

[light]

If the only augmentation being requested here is that CFDAO proposals get paid ANT instead of / in addition to DAI then I recommend interested parties write an AGP to augment CFDAO’s funding accordingly. Also, as soon as Open Enterprise is ready on mainnet we can begin experimenting with those tools as well.

[burrrata]

I also think it would boost the participation in the AGPs which is a metric I think we should be optimising for (probably not by much but it’s a step in the right direction)

ANT is a governance token. Giving the community a stake in governance, and thus encouraging them to vote, is essential for the community.

Also experimenting with DAO initiatives like seems like something we should be supporting, especially when the cost very little and potentially have a big upside

Yeah, I mean… isn’t that the point of this forum? DAO research and community development?

If the only augmentation being requested here is that CFDAO proposals get paid ANT instead of / in addition to DAI then I recommend interested parties write an AGP to augment CFDAO’s funding accordingly.

Dawg… how can I make this more clear? This thread is about 2 things:

• a place for community contributions to documentation and tutorials
• incentives and rewards for people who contribute to community documentation

There is currently no dedicated place for this, esp since dev stuff is being removed from the wiki. There is also no mechanism to encourage or reward contributions beyond just asking for money. Aragon needs to step up it’s game when it comes to dogfooding Aragon to support it’s own community.