1Hive Docs Standard

[yeqbfgxjiq]

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:

• A docs template that will ship with the 1Hive DAO Kit that will allow people to easily create documentation for their own apps/projects.
• Once created this docs template can be used to document new 1Hive apps.
• If successful, this docs template could potentially be expanded to improve documentation for apps across the Aragon ecosystem.

[yeqbfgxjiq]

Examples Of Docs

Great Docs

• Ask HN: What's the best documentation you've ever read? - many options
• Docusaurus - my personal favorite
• Rust - one of the most loved programming languages due to their awesome community development initiatives like standard documentation, user onboarding, and guides/books

Good Docs

• hack.aragon - beautifully organized, but sometimes out of date and/or buggy
• Plasma Group - easy to explore and looks cool, but also sometimes out of date and/or buggy
• Nest.js - beautifully built with Docusaurus
• ReactJS - easy to use, follow, and reference (it "just works")
• MDN Web Docs - kind of the backbone of the internet, but a little busy and suffering from feature creep
• bs4 - the docs don't look pretty, but using Beautiful Soup 4 is so easy that it doesn't matter, and ultimately the goal is to make the apps/protocols easy to use

Aragon Docs

• links to Aragon and TPS docs materials - in case we need them

[yeqbfgxjiq]

Docs Template Outline

Moved this brainstorm to it's own repo to test/build within the context of using an external website/docusaurus to display info.

• https://github.com/1Hive/standards

[yeqbfgxjiq]

Automagic Code Comments

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

• https://github.com/aragon/hack/tree/master/website/scripts

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.

[yeqbfgxjiq]

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.

• docs/guides for everything goes in the repos for that thing
• then the website then just pulls them in, but the website doesn't hold any hard coded copies of documentation

DAO

• scripts to deploy DAO
• tbd: template to deploy DAO
• docs explaining the org structure of the DAO

Redemptions App (or any other external app)

• code for the app
• docs for the app

Communications

• docs explaining the communication channels of the org (keybase onboarding guides, etc)

Website

• Docusaurus with project specific themes, content, and blog/wiki
• syncs with relevant repos to pull in the freshest versions of all documentation. This makes the website a front end webdev project (easier for people to contribute) and it also reduces the need to bug web devs every time something gets updated on a project (DRY)

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.

[yeqbfgxjiq]

More concretely, that looks like:

1Hive Website Repo

In https://github.com/1Hive/website/docs/contribute/:

• moving github.md and keybase.md to a docs folder in the communications repo
• moving everything else describing the DAO membership/participation structure to a docs folder in the dao repo

In https://github.com/1Hive/website/tree/master/docs/projects:

• linking to a welcome or introduction page in the docs section of each project's repo rather than having it hard coded into the website

In https://github.com/1Hive/website/tree/master/docs/wiki:

• If this standard was adopted across the Aragon ecosystem we could link to everything, but... it's not. As is, this section can stay the same and every project that forks the DAO Kit can just update/maintain their own Wiki.

1Hive DAO Repo

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.

1Hive DAO Kit

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).

[yeqbfgxjiq]

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 :)

[yeqbfgxjiq]

Created a repo to work on the docs standards as a stand alone thing that people can reference:

• https://github.com/1Hive/standards

[yeqbfgxjiq]

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