CANCELLED - Hack.Aragon 4 All

📔 Archive CFDAO
#1

Hack.Aragon 4 All

A world class developer experience for every Aragon project


Abstract

I’ve been exploring the Aragon ecosystem for a while now. This has been an amazing journey, but it has not been easy. It’s often hard to find information, or when you do find it, it’s in a confusing format. This is a huge problem. For most developers their most scarce resource is time. In the information age platforms that are easy to use get more adoption. End of story.

Furthermore, most developers want to innovate at the bleeding edge of whatever cool project they’re building. They don’t want to spend time on documentation and community building. In fact, most often documentation is viewed as a chore or even a nice-to-have. This results in confusing, out of date, and unintuitive documentation. This creates a poor developer experience and hinders adoption.

Developers who want to build things need solid documentation, but developers who are building things view documentation as a chore. This ruins the experience for everyone. It doesn’t have to be this way. There are wonderful tools that make it easy to create beautiful intuitive documentation. Hack.aragon is a testament to this. It’s honestly one of my favorite things about Aragon. The problem is that Aragon projects like Autark, Black, and more that will come in the future don’t have the time or resources to put together such a cohesive and seamless developer experience. This is going to become more and more of a problem as the Aragon ecosytem scales. I’d like to fix that. I’d like to help every Aragon project create intuitive documentation and a hack.aragon style developer hub for their project.


Deliverables

There’s a few steps that would go into making hack.aragon style developer hubs available for any Aragon project:

  • a documentation standard
  • a kit that walks people through setting up a website, documentation, developer hub similar to hack.aragon

Creating these will allow Aragon projects to better showcase their work. It will also improve the experience of documenting and maintaining that work. Making this work easy to do increases the liklihood of that it will actually be done.

Furthermore, it will improve the experience of new developers trying to learn about and use Aragon apps. Imagine if every Aragon project could have a developer hub as good as hack.aragon. It’s possible. This proposal is to build demos of what that might look like. If successful, I will then go on to create a Nest Grant to generalize the process and make it available for everyone :slight_smile:

Aragon App Documentation Standards/Templates

What makes a standard “standard?” Well, the fact that people actually use it. My goal is to gather feedback from across the Aragon ecosystem (A1, Autark, Black, 1Hive, and more) to create a template/guide around documentation. This could serve as a reference for every future Aragon app developer so that there is consistent and cohesive documentation across the entire ecosystem. Curious what that might look like? Check out the Rust community. They are one of the most loved and fastest growing programming langauges in the world. Why? They have a culture of excellent documentation and community development. Learning, building, and contributing to Rust is a joy. People love it. I want that for Aragon too.

So how do we get there? We start. There’s power in just starting. With that in mind, I’d like to document Autark’s TPS apps. They’re awesome. People are using them. They need to be documented. This will serve as a testing ground to work with the Autark team to understand their goals and pain points around documentation and developer UX. That feedback will be rolled into a documentation “standard” that will be used to document all TPS apps. Once the draft for this “standard” is created, we can then get feedback on it, improve it, and provide it as a resource for everyone to use.

More concretely, this “documentation standard” will include, but not be limited to:

  • overview: basic info about an app
  • user guide: how people can use the apps to do stuff
  • dev guide: how to install the apps into a DAO and/or hack on them

Hack.Aragon Developer Hubs For Everyone

To showcase that work, I’ll create a hack.aragon style dev hub for Autark showcasing their work and making it easy for people to learn about and build with their apps. This will leverage the same framework and syncing structure that Aragon uses. What this means is that every project/app will maintain their own documentation in plain markdown the repo for that app. Then, anyone who wants can sync that documentation into their developer hub and display it using the custom CSS/theme of their website. This is what hack.aragon does now, and it’s possible for everyone.

Beyond just making your own project look good, this will enable other projects that use your app to sync your docs into their developer guides. Yes that’s right, you’ll maintain 1 source of truth for your docs and whenever you update them they will automagically be updated for everyone else too. This will allow people to install your apps into their DAO as well as your documentation and guides into their dev hub.

Again, how do we get there? We start. A dev hub for Autark will showcase the awesome power of TPS, the insane flexibility of hack.aragon, and the modular interoperability of the Aragon ecosystem overall. If successful, I’ll then expand this demo into a generic developer hub kit that any Aragon project (current or future) can use to create a world class developer experience for their users.

Summary

The “source of truth” for documentation would be in docs folder of the repo for each Aragon app. That folder would hold Markdown documents that the developers of that app would maintain in that repo. Those documents can then be synced (automagically copied) into any hack.aragon style dev hub.

This allows projects can easily create their own developer experience around their Aragon apps that’s always up to date

  • overview / landing page
  • contributing guide
  • blog and social links
  • user onboarding guides
  • dev guides (installation and hacking)
  • links to the #dev chat for questions
  • etc…

This would also allow hack.aragon (or any other project) to sync in a “master list” of every Aragon app in a convenient centralized location.

It would also allow communities/organizations that use DAOs to easily create a landing hub and onboarding guides for their community. Rather than syncing in all the documentation for each app, they could just sync in the user guides.

There’s a lot of possibilities, but right now it takes a lot of time and expertise to set up initially.

The hard part is first getting the dev-hub setup so that the sync works, then getting the docs standards setup so that everything is cohesive. After that, syncing in docs requires changing a few parameters in the Docusaurus dev-hub (currently this takes me ~ 5min). Then the ReactJS automatically generates documentation pages from the Markdown documents that are synced in, but in the style of the website that those docs are being synced to. Hack.aragon currently does this with the CLI and AragonJS docs, and the Autark dev-hub demo does this with the Temp TPS Docs.

My goal is to make the initial setup process for all of this go from multiple weeks/months to < 1 week. This can be done with a documentation standard for Aragon apps and an easy to deploy template for creating a hack.aragon style dev-hub.


Development timeline

Prior work completed

Estimated time to full completion: 1.5 months

  • Documentation Standard Drafts: 2-3 weeks to gather feedback, iterate on models, and reach consensus on a “standard”. This format would then be used to create TPS docs as a demo.
  • Developer Hub Demo: 2-3 weeks to create the initial model, incorporate feedback into edits, and ship. The demo for this would be an Autark TPS developer hub making it easy for people to learn about, install, and hack on TPS apps.
  • Snafu’s and unknown unknowns: 1-2 weeks to deal with the inevitable things that always delay software projects.

Grant size

Ask: $5k

  • $1k for the documentation standard drafts
  • $1k for the user/dev guide standard drafts
  • $3k for the dev hub demo w integrated docs

Notes

If you’re still not convinced, let me ask you this…

  • How long did hack.aragon take to build?
  • How much did it cost?
  • How long would it take and how much would it cost if another Aragon project wanted to recreate that type of developer hub for their project?

What if we could get that cost down to 1 week and free?

This proposal is an initial step towards that goal.


10 Likes
Aragon Network Token 🦅
Nest DAO Ideas & Issues
#2

Already started working on this. You can track progress here:


You can also compare the experience of the Autark Dev-Hub Demo to navigating the current website, blog, and GitHub repo. Imagine you’re building a DAO for your community/organization. You want to learn about and potentially install a few TPS apps. Pick an app (say Allocations or Projects) and try to learn about what it is and what it does. Then figure out how to install it into your DAO. Now figure out how to tell your community about it to make sure that they understand it and can use it. Bonus points if:

  • you pretend you have a question along the way and need to reach out to the team
  • you pretend you just heard about TPS on Twitter and the major TPS resources weren’t conveniently aggregated into links for you to follow in this thread

I guarantee this experience will be an order of magnitude more difficult than exploring the Autark dev-hub demo.


Project Notes:

  • Most of the work is happening in the DEVELOPERS section of the dev-hub. The goal is to develop the overall framework/architecture first, then upgrade the content. Atm everything is a placeholder, including the documentation content.
  • To prove to myself that this process works, I set up the website/dev-hub skeleton and doc sync scripts on Saturday. Today, Sunday, I edited the demo Markdown documents using the GitHub web app (nothing fancy). These docs are in a separate repo from the website. With one command I was able to sync and publish the new docs to the dev-hub and display them in the context and styling of the website. Now of course the styling of the website is minimal and the content of the docs was aggregated from what already existed, but it proves that the mechanisms work.
  • This means that soon, any Aragon project will be able to easily create and maintain Markdown documentation in the GitHub repo for their apps/projects, then easily sync that documentation to be displayed in their website/developer-hub, and as a result have a great developer experience that increases adoption for their apps/projects :slight_smile:
2 Likes
#3

Hey there, totally agree that Aragon has a long way to go to make things much easier for newcomers and even recurring users. In this regard personally think this is a really cool initiative. If standard gets adopted it would enhance UX and hopefully lower bounce rate significantly.

For that ofc the standard would still need to be adopted and therefore i’d be eager to hear more from other Flock and Nest teams. Maybe you could use the Aragon Address Book and push this post to some of them so they can comment their appetite for the proposal? Let me know if you need help on this

1 Like
#4

Hey thanks :slight_smile: I’m really excited about it too

Already reached out to some people in A1, Black, Autark, and or course 1Hive, but it seems like most projects don’t have a single person to reach out to regarding documentation and dev UX. This results in a tragedy of the commons situation where every team cares about docs and dev ux, but everyone’s also busy with other things. If you could make introductions that would be awesome, but I think what would be even more impactful is coming to the table with a concrete spec/demo. That way people can see what the project will look like, how they could benefit from it, and how it could be improved to solve their pain points vs just a giant open ended brainstorm.

To get create a concrete spec/demo that I can get feedback on, I’m creating this grant to sketch out an initial prototype with Autark. After that, I’ll create a Nest Grant so that I can spend time engaging with the broader community to upgrade and generalize the model into something that everyone wants to use :slight_smile:

1 Like
#5

I would like to see some organic demand from the development teams in question for a solution like this, and some commitment that they will actually use it and keep it up to date. I also wonder if a website is the best format or even necessary if there are good docs in the repo itself. Not every project needs a fancy docs site. Often times well-formatted, well-documented README and CONTRIBUTING markdown files are good enough.

#6

As stated in the proposal, part of the problem is that developers don’t want to write documentation. They view it as a chore. For the Aragon ecosystem to scale successfully, it needs to be easy to learn about and use Aragon apps. This means we need to create tools that improve the developer experience for Aragon app devs as well as devs who want learn about Aragon apps to to build and improve their DAOs.
The Autark team has stated that they would really appreciate tools that improve this process. Talking to other Aragon teams as well, this is a common pain point. That being said, there hasn’t been a clear solution or the incentives to solve the problem until now. I’d like to change that by creating a model/demo of what’s possible, then sharing it with the broader community to improve it into something that everyone wants to use :slight_smile:

#7

I’d like to see validation from the users of this tool (Aragon devs) that it is the best solution to the problem of them not wanting to write good docs. Before spending money to build a solution we should spend some time validating that it’s the right solution.

Also I would separate out the issue of user docs from developer docs. These may require different solutions e.g. while we put developer docs on hack.aragon.org, we put user docs in Help Scout. We haven’t decided Help Scout inclusion criteria for apps that aren’t in the aragon-apps repo yet but if user docs are part of the scope of this proposal then it may be good for us to settle that before we conclude that user docs should be with developer docs in a separate website.

#8

It’s not in a separate website. It’s anywhere you want. The point is to have a single source of truth for information about an Aragon app in that app’s GitHub repo. Then that source of truth can be synced to whatever platform, website, or developer hub you want.

To make that happen there needs to be a base line of standard information that is released with every Aragon app (docs standard). Along with that, an easy to deploy hack.aragon template would go a long way to making it easier for Aragon projects to showcase their work and create a cohesive end-to-end developer experience around their apps/projects (dev hub). Combining the two will help the ecosystem thrive. As is, a lot of people I’ve talked to, myself included, have had a lot of difficulty finding information and understanding which projects are working on what and how all the Aragon apps work.

Yes, the main Aragon website, hack.aragon, and the new help.aragon are great for the core team. They don’t help all the other projects that are building on Aragon though. As the Aragon platform scales it’s going to be more and more important that there are resources to help projects can showcase their work in a cohesive, accessible, and autonomous manner. It’s essential.

#9

I appreciate the entrepreneurial mindset behind this proposal! I just think it may be premature to jump into development.

This is how I think about product development.

When developing a new product (or even a new feature to an existing product) we need to validate two things: the problem and the solution.

To validate the problem, we have to make sure we’re solving the right problem, then we need to make sure there are enough people who have the problem to make it worth solving. We do this by developing a “problem hypothesis” that we then validate through a series of user interviews. Once we validate our problem hypothesis, we can then focus on developing a solution to the problem.

To validate the solution, we come up with a minimal (but workable) solution (a “Minimum Viable Product” or MVP) to the problem and test that with the people who originally validated the problem hypothesis. We then iterate on this solution based on user feedback to develop a final polished product.

Based on the information in this proposal and the followup comments, I think you’re at the early stages of developing a problem hypothesis, but haven’t fully developed or validated it yet, and are jumping ahead to developing an MVP and seeking funding to deliver a final polished product. I just want to make sure we don’t get ahead of ourselves :slight_smile:

Before voting to approve this proposal I would like to see a concrete statement of the problem hypothesis (e.g. who exactly the user for this is: existing app devs, new app devs, app users, all of the above, etc, and what problem is being solved for the target user) and information that validates the problem hypothesis (e.g. interview notes, or even some supporting comments here on the thread from folks you’ve talked to saying “yeah, that!”). Then I would like to see some early validation of the solution being presented to the validated problem, again user interview notes and/or supporting comments here on the thread would work. If you need any help with this process I recommend checking out this neat tool called Javelin.

After I see a validated problem hypothesis and a validated MVP then I would be open to approving funding for a final product.

(Let me know if I’m misreading or misunderstanding anything!)

6 Likes
#10

Lots of good ideas in here and happy to see a cross-network effort.
As we are soon launching Pando upgrade with UI based markdown editing we’ll be using it for our documentation as dogfooding. As a remote git helper these documents will also be pushed to our github repos.
FYI in charge of documentation for AB apps if you have any questions for the team :slight_smile:

4 Likes
#11

Those are all great points, but this is a $5k experiment.

  • Downside Risk: $5k
  • Potential Upside Reward: better docs and UX for devs in the Aragon ecosystem

If the Aragon community isn’t comfortable deploying capital to support and test out community ideas, and wants to see a due diligence report to address any potential risks, even on projects of such a small scale, then I think I’m in the wrong place.

At some point you have to start taking shots on goal. We’re in one of the fastest growing most competitive industries in the world. Playing defense isn’t going to make Aragon the most successful platform in the world for decentralized organizations. It’s also not going to make anyone want to contribute or get involved.

#12

I think it’s important we instil discipline into the projects we fund to do the proper due diligence / research necessary to ensure that this is a good use of funds (after all, this is not just one a one-shot deal, if it gets built and deployed then it also has to be maintained over time, and will require continual investment). I think you’ve made a good start here but I would like to see more information that validates the problem hypothesis and proposed solution. It’s not just about the $5k it’s about setting a good example for other projects to follow too. This is my own standard for voting yes on a funding proposal, of any size.

As an alternative to this proposal requesting funding for a full, not-yet-validated solution now, you could either request a smaller grant to conduct this user research before going for a bigger grant later, or (my preference) do the research ahead of time then build in back-payment for the time spent on research into your final proposal. If you later decide not to pursue the project for any reason then you can submit a smaller proposal to compensate just for the time spent on research, which I would gladly vote yes on if notes and logs from the research are shared with the community.

2 Likes
#13

I found hack.aragon to be an excellent resource. As a non dev, it’s really difficult to experiment with the various apps and cli. I standardised resource for all Aragon apps would make the learning a bit less steep

1 Like
#14

I am cancelling this proposal.

I want to build things. I want to improve humanities ability to coordinate and solve problems. I want to support a world where anyone, anywhere, can contribute to open source development of the commons sustainably and fairly. I really do believe that decentralized organizations can solve the world’s most challenging problems. I want to help make that happen.

While Aragon is working on many of the same problems that I care about, I can’t continue contributing if community members aren’t supported. Due diligence on such a small scale experiment is simply unreasonable and not worth the opportunity cost of time. I used to participate in the angel/VC world, and one of the most common mistakes of inexperienced angel investors was spending too much time on risk management/analysis and not enough time supporting entrepreneurs. The best angels knew that almost all startups were doomed to failure, but that if they could increase the odds of success just by a little bit they would increase the value of their investment. These angels and startups are the ones that went on to raise more rounds. The startups that spent time on due diligence packets rather than product all failed. There’s a time and a place for due diligence, but it’s not when you’re trying to build a prototype to find product/market fit.

If you want to change the world, you have to do something different. If you’re doing something different, it’s not going to fit into a neat little box that you can model and validate easily. If it does, then it’s a commodity that’s going to be subject to intense competition. Pushing forward the boundary of innovation is risky, generally confusing, and often controversial. That’s what Aragon is doing with DAOs. We’re trying to change the world by changing the way people coordinate and cooperate. Most people don’t get it, but it’s a risk worth taking. I hope that moving forward, the Aragon ecosystem will internalize that attitude to take risks supporting community related endeavors as well.

1 Like
#15

Lean startup / customer development methodology (which I like to use and recommend for all product developers) would say this is exactly the time that you want to do the user research I was suggesting, especially if you’re asking others to pay the up-front cost of funding product development. You offered no data supporting that your proposal was the correct direction to build in. If you did the research, found it supported your hypothesis, and shared the research results here then your proposal may have gotten at least my support.

I once again invite you to check out that Javelin tool I linked to, which offers an easy way with step by step instructions for developing and validating a problem/solution hypothesis. I’m not asking for a ton of work from you, just a few hours to develop a clear problem/solution hypothesis and doing interviews with potential users of the tool you’re trying to build with the goal of validating or debunking your hypotheses. This way we can make sure you’re solving the right problem and that your proposed solution is actually the best solution to that problem. Maybe in the course of the interviews we find out there’s a more important problem to solve that requires a totally different solution. Without doing this up front work we don’t know, we’re just building off a hunch with no real data to back that up.

2 Likes