Hack.Aragon 4 All
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.
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
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
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.
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
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.
Prior work completed
- Started sketching out an Aragon app documentation standard might look like and also started exploring what user guides for a few TPS apps might look like.
- Recreated the hack.aragon document syncing feature in a side project.
- Built many websites using the same framework (Docusaurus) that hack.aragon uses (Coop DAO Docs, 1Hive, and Molochasaurus).
- Now I’m combining all that into a cohesive package using Autark’s TPS as the demo. Starting that work here
- See comment 2 in this thread.
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.
- $1k for the documentation standard drafts
- $1k for the user/dev guide standard drafts
- $3k for the dev hub demo w integrated docs
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.