Closed yeqbfgxjiq closed 5 years ago
Moved this brainstorm to it's own repo to test/build within the context of using an external website/docusaurus to display info.
A script to pull code comments from the codebase into the docs. This makes it easy to keep the docs up to date because there is always a single source of truth: the code. Rust does this and hack.aragon does this as well. It would be awesome if we could generalize this feature to something that the entire Aragon ecosystem could use :)
The script will fetch the docs on each repo to get the last version and build the Docusaurus markdown files.
Aragon Docs Scrips
Got the sync script that @0xGabi shared (more or less) working! This allows the docs section of the website to merely be a UI/Client that pulls and displays information from the docs
folder of other repos (like the redemptions app, aragon cli, whatever).
This means that each app/project/thing can maintain their own documentation, and then any projects that use the app can easily pull the documentation for it into their website/docusaurus and display it with the theme/styling and context of their project/experience (like hack.aragon does currently).
Anyways, just brainstorming out loud here, but that format seems to be working with hack.aragon and it also seems like it would be really really useful for other projects in the ecosystem to adopt as well.
Ok... so I'm building out the actual Docusaurus guides for the 1Hive DOA Model, and it's quickly becoming clear that it makes way more sense to sync things rather than have them hard coded into the Docusaurus. Part of that involves describing the 1Hive DAO model. Since the DAO, the docs describing the DAO, and the template to deploy the DAO will change over time it makes sense to have the kit sync with those so that users always get the latest version. Currently this means that the docs describing the DAO model need to be in the dao
repo rather than the website
repo.
Essentially, we need to reorganize the way our GitHub repos are organized.
DAO
Redemptions App (or any other external app)
Communications
Website
Overall this will allow every team (apps, communications, DAO architecture, etc...) to manage their own projects internally without continuous overhead/coordination with the rest of the hive. It will also allow anyone who wants to incorporate a project/app into their DAO/community to not only install the code to their DAO, but also the docs to their Docusaurus. All the latest content will always be synced without any overhead or coordination.
More concretely, that looks like:
In https://github.com/1Hive/website/docs/contribute/
:
github.md
and keybase.md
to a docs folder in the communications repoIn https://github.com/1Hive/website/tree/master/docs/projects
:
welcome
or introduction
page in the docs section of each project's repo rather than having it hard coded into the websiteIn https://github.com/1Hive/website/tree/master/docs/wiki
:
I think it makes more sense to develop the template (#3) in the dao
repo rather than in this repo. That way the scripts, template, and docs for the 1Hive DAO are all in 1 place.
This will be an end-to-end guide on how the 1Hive DAO model works, how to deploy it, and how to build an organization around it. It will be a 1-stop shop combining tools from the 1Hive ecosystem (DAO template and docs, website content, and 1Hive docs guides/examples).
LMAO just realized that I can do this by copying the docs rather than moving them. I'll do that to test this idea out, and if you guys like it, we can move forward with the model on new projects. Either way the old setup for the website/docs will still be there so it's all good :)
Created a repo to work on the docs standards as a stand alone thing that people can reference:
Moved this to https://github.com/burrrata/hack.aragon4all
Also, this is now being discussed in the context of 1Hive here: https://github.com/1Hive/website/issues/36
Part of the mission of 1Hive is to create tools that make it easier for people to learn about, use, and build DAOs to empower their communities. As such, it makes sense that the 1Hive DAO Kit ships with basic docs, user onboarding guides, and templates for both. This standard documentation framework will be used to document all the apps used in the 1Hive DAO model. This will also include a doc creation guide that will help communities create new docs that are organized and informative as they extend and modify the DAO.
Objective: