Suggested changes for apm-ref.md:

• Include an introduction/definition for APMRegistry

• Better links

See the discussion in #95

I notice that bullet points are displayed weird. Not sure why this happened. It would be great they be like in create-react-app docs

It'd help new developers getting started to have a recommended workflow for their own apps.

At Aragon One, we typically develop apps following this flow:

1. Define requirements for the app:
   • Contract: storage, getters, and events
   • Frontend: mock ups
2. Build contract
3. Build frontend
   1. Build self-contained UI components
   2. Unify components into an implementation of the design that uses mock data (usually just a JSON file)
   3. Connect UI to real chain data
   4. Allowing users to "write" data by creating transactions

Aragon has changed the names of certain components recently:

• Aragon Package Manager ==> aragonPM
• Aragon CLI ==> aragonCLI
• Aragon Core ==> Aragon client
• aragon.js ==> aragonAPI
• Aragon UI ==> aragonUI
• Aragon ID ==> aragonID

Make the same changes for images and diagrams on hack.aragon.org. These need fixing:

• header image
• main diagram
• header image
• header image

PR aragon/aragon-cli#253 introduced aragon apm info and aragon apm packages commands that need to be documented

Currently we have the wrapper documented in both:

https://hack.aragon.org/docs/aragonjs-ref.html#wrapper
https://hack.aragon.org/docs/aragonjs-ref-clients.html

Solution A:

• remove the "Reference documentation for client/wrappers" (although it seems to be the one that's more styled/mantained)

Solution B:

• remove the Wrapper section from "Reference documentation"
• rename this section to "Reference documentation for wrappers" as calling this a client is very confusing

See aragon/aragon-cli#26.

Most of the diagrams used on hack.aragon could be improved by doing the following:

• increasing the font size; in a lot diagrams some of the text is hardly legible
• use some color

@izqui made this diagrams originally and may have the source files.

See https://forum.aragon.org/t/on-aragon-naming/203/12:

Currently, when clicking on aragonAPI in the developer portal, one is redirected to the aragonJS root page. The first package mentioned is @aragon/client, all the while the repository is aragon.js.

We should create a different landing page for aragonAPI itself, that points to aragon.js and @aragon/app as being the JavaScript implementations of aragonAPI.

Document the specs in https://github.com/aragon/specs as well as the schemas and definitions of the arapp.json

I tried following this "Your first Aragon app" tutorial. When I run aragon run command, got an error bellow:

 ❯ Start a local Ethereum network
   ⠴ Setting up a new chain from latest Aragon snapshot
     Starting a local chain from snapshot
   Check IPFS
   Publish app to APM
   Create DAO
   Open DAO

/Users/yutaro/.nodebrew/node/v9.5.0/lib/node_modules/@aragon/cli/node_modules/ganache-core/node_modules/level-codec/index.js:44
  return this._valueEncoding(opts).decode(value)
                                   ^
SyntaxError: Unexpected token o in JSON at position 1
    at Object.parse [as decode] (<anonymous>)
    at Codec.decodeValue (/Users/yutaro/.nodebrew/node/v9.5.0/lib/node_modules/@aragon/cli/node_modules/ganache-core/node_modules/level-codec/index.js:44:36)
    at /Users/yutaro/.nodebrew/node/v9.5.0/lib/node_modules/@aragon/cli/node_modules/ganache-core/node_modules/level-sublevel/nut.js:122:34
    at /Users/yutaro/.nodebrew/node/v9.5.0/lib/node_modules/@aragon/cli/node_modules/ganache-core/node_modules/encoding-down/index.js:57:5
    at /Users/yutaro/.nodebrew/node/v9.5.0/lib/node_modules/@aragon/cli/node_modules/ganache-core/node_modules/cachedown/index.js:61:5
    at /Users/yutaro/.nodebrew/node/v9.5.0/lib/node_modules/@aragon/cli/node_modules/ganache-core/lib/database/filedown.js:28:5
    at FSReqWrap.readFileAfterClose [as oncomplete] (fs.js:528:3)

In the Publish guide the link to Troubleshooting guide.

In the Custom deploy guide the link to sign transactions using a private key.

e.g. https://hack.aragon.org/docs/kits-intro

See: https://forum.aragon.org/t/on-aragon-naming/203

aragon/aragon-cli#230

It’s Luis’ wish to remove Metamask as a must-have in the docs when Frame is ready for prime time. Could we make the docs agnostic?

Include them in the tutorial

During this move, implement features as described here. Also include issue #63.

Reasons discussed in aragon/aragon-cli#364

New Features:

• create-aragon-app #74

• dao act

• dao token

• apm grant

• --environment usage #53

Guides

• Luke’s guide

• Publishing #33

FAQ

• Initialization of global variables in apps #76

• Windows specific considerations #77
  Issue sending tx

• Errors related to delete the ./ipfs directory

• ipfs not running

• How to verify contracts onchain

• Explain when use the parameter wsRPC in arrap.json. Connect to custom endpoint

• Set a private key to sign tx (https://aragon.chat/channel/dev-help?msg=KmDvP8YP27FjhfhWf)

• Propagating content hash

• ./aragon directory

Update

• Existing tutorial #15

• init

• run

• devchain

• dao new

• dao upgrade

• dao install

• dao exec

• apm publish

• Remove metamask #70

Note: For a more in depth review check this file

Document how to use Frame to interact with the DAO created in your first aragon app tutorial

As pointed out in both the WHG and CD audits, we should make sure to document and highlight the contract functions that are insecure or incredibly powerful.

Examples:

• Kernel.setApp()
• EVMScriptRunner.runScript()
• ACL permission functions

An interesting tidbit from That Planning Suite (https://github.com/spacedecentral/planning-suite/blob/dev/docs/DEVELOPMENT_NOTES.md#wrong-fonts-colors-or-browser-console-errors):

Aragon provides the command copy-aragon-ui-assets and we use npm run sync-assets to call it. The problem is that is easy to have errors configuring the path in AragonApp component (from @aragon/ui), because is not documented where the slashes go or things like that, even some original Aragon apps have or had this error.

Without relative paths, most things will fail on IPFS, and we should point that out in tutorials and documentation.

As someone who's starting out getting to know the aragon ecosystem, I often ran into cases where some terminology used throughout the project threw me off as they had a different meaning than what I've expected.

This can be simple cases like

What is an APM Repository?

Is it a Git repository? Is it just an implementation of a different kind of repository?

Or

What is a package in APM? What does package even mean in this context?

As many people here know, APM takes care of a lot of things (distributing content via IPFS, deploying app contracts, managing versions via APM Repositories and so on.

I think it'd be good to introduce a glossary in the developer portal that gives short and concise explanations of the terminology that's being used, especially for the ambiguous ones.

If the team and community agrees that this is something that should be added, we could start collecting all the terms here that should be covered by the glossary.

Here are a few:

• Aragon CLI
• APM (Aragon Package Manager)
• APM Repository
• Aragon Apps / Sandboxed Apps
• Aragon UI
• Wrapper (I wish there was a less general term for this thing 😅)
• Aragon DAC
• aragon.js
• aragonOS
• DAO Kits
• Aragen
• aragon-id
• DAO (sure, Decentralized Autonomous Organisation, but in the context of Aragon it could also mean the organisation represented in the app, or the app itself even?)

And there's prolly a lot more (feel free to add them here). Again, as someone who's new to this universe will be very overwhelmed by all the different components and how they fit in the big picture.

I also hope that, before a 1.0 there's opportunity to maybe even rename some things and streamline the terminology as much as possible.

This issue was funded with 150 DAI, see more issues on our dao projects app.

1. In depth guide on how to install the Agent app with aragonCLI. We assume we start with a democracy-dao created with the on-boarding page.
2. Show a good use case of using the Agent app.

Note: Opening a Maker CDP would be great, open to suggestions 🙌

TODO:

• Introduction to the Agent app and how it work

• How to interact between two DAOs

• Deploy a DAO using the agent app

• Interacting with Compound

• Creating an Aragon Trust

• Opening a Maker CDP

in progress here

Create a CONTRIBUTING.md file and contributor guidelines for this repo.

I notice on the CLI page for example, the npm and git commands are entered, which assumes that the user has these installed already. It would be worth noting at the beginning of the documentation what dependencies are required to go through the documentation (including the minimum version required) and how to install the dependency.

In order to showcase Aragon apps on the upcoming app center, we need to explain how to prepare:

• Small icon
• Bigger icon
• Description
• Screenshots

That should be documented and added to the dev portal.

The docs here aragon/aragonOS#314 could be a good addition to the dev portal

We use the fields in manifest.json in aragon/aragon and it's not obvious what is needed and what each field does.

https://github.com/aragon/hack/blob/master/docs/getting-started.md#quick-start

Section needs to also say:

• cd into the new directory created and
• do aragon run and localhost will eventually open in a browser window

Some API documentation links are broken, here is the list of the ones that I've found:

• Kernel API documentation
• AragonApp API documentation
• Forwarders and EVMScripts API documentation

Please, if there are others API doc links, ensure those are working correctly as well.

• Remove API from the top navbar
• Have the aragonOS ref documentation as one item inside the API sidebar
• The aragonOS link from the top navbar should go to the reference documentation, but as that page will have the API sidebar, the dev will be able to nagivate there too

Topics to talk about:

• Document usage. Needs to be updated because now most commands are under aragon dao and aragon apm (or just dao and apm)
• Document how to import keys from aragon devchain and local chain URL into MetaMask/others.

I think line breaks between elements for the reference docs would be really helpful. I keep reading on past the return.

There's a few things that are confusing, e.g. are we using the bare or react boilerplate? Or are we getting them to make the contracts themselves?

• Update aragon init <app-name> [template] command documentation (Getting started, kits-intro and cli-usage sections)

• Create new documentation for create-aragon-app <app-name> [template] generator

We recently got approved for the beta version of github actions. Set these up so that they run npm run publish-gh-pages on every commit to master.

see the tutorial proposal

Currently we are doing this here, but would it make more sense to have the docs generation in aragonOS repo and pull them from there?

They likely also need the windows-build-tools package installed if they have problems installing the CLI or any other dependencies.

Now the user is asked to use aragon init foo.aragon.eth react this command generate a dev environment with lots of files that could lead the user to mislead

I usually like to have apps running while i read the documentation. But in the tutorial, the process for getting the app running starts with

Let's first set up our project.

npm i -g @aragon/cli

Next, we bootstrap our project:

aragon init foo.aragonpm.eth

and then goes into many pages of documentation. Towards the bottom of the page, we see aragon run. It also doesn't mention npm install at all, which I forgot to do at first.