Wiki Editorial Policies
- If you create a page, you are the “owner” and responsible for keeping it up to date, unless a different owner is mutually agreed upon. The owner should be named at the bottom of the page in the format "Page owner: Firstname Lastname (@githubname)".
- Pages that are not kept up to date may be archived by the Wiki maintainer if the owner is unresponsive.
- The maintainer will ask the owner of a page to review any proposed changes by third parties and, if otherwise unobjectionable, merge them in good faith if the owner is unresponsive for more than two weeks.
- The maintainer will review open pull requests once per week, give feedback, and respond to any replies to earlier feedback until the PRs are ready to merge. PRs that are ready to merge will be merged within one calendar week.
- Draft pull requests are used for PRs that are still a work in progress and not ready for review. PR descriptions should reference the issue number that the PR addresses, if any e.g. "Closes #123", which will automatically close issue #123 when the PR is merged.
Labels used for PRs
- Documentation: adds new documentationw
- Enhancement: improves existing documentation or Wiki layout
- Meta: closes a Meta issue
Labels used for issues
- Bug: something is wrong
- Documentation: request for new documentation
- Enhancement: improvement suggestion
- Meta: discussion about the Wiki or Wiki repo itself
Wiki writing style guide
We have a style guide that contributors should follow to maintain consistency and ease of understanding throughout the Wiki.
There is no such thing as an “Aragon core dev”. Anyone who has had a contribution accepted to an Aragon software repo is an “Aragon dev”, and the use of the term Aragon dev is not heavily policed; that is, it’s a big tent as long as someone really is developing Aragon software.
The plural of AGP (Aragon Governance Proposal) is “AGPs”.
- “AGP proposals” would be redundant (“Aragon Governance Proposal proposals”).
When referring to votes held by the Aragon Network, the generic term is “Aragon Network vote”, while if you are referring to a specific vote, you will say “Aragon Network Vote” followed by which vote, as identified by its number e.g. “Aragon Network Vote #1”.
- It has become common practice in the community to shorten this to “ANV” e.g. “ANV-1”.
The term for people who hold ANT is “ANT holder” or “Aragon Network Token holder”.
- “ANT token holder” would be redundant (“Aragon Network Token token holder”).
- Related: when referring to ANT, simply say “ANT”, not “ANT token”.
- Related: the generic term for someone who holds a token is “tokenholder”, a variation on the word “shareholder”.
“The thing you create using the Aragon client and aragonOS” is called an “Aragon organization” or simply “organization” if there are multiple people, or a “smart account” if it is used by one person.
- We focus on the organization use-case but do not ignore “single player” use cases for smart accounts.
- Some Aragon organizations are DAOs, but not all of them.
“The thing users install to add functionality to an Aragon organization” is called an “Aragon app”.
- “Aragon App”, “Aragon module”, “Aragon plugin”, etc. would be incorrect.
Ethereum is always capitalized, the word “blockchain” is not.
- By the way, “blockchain” is a one word (not “block chain”) concrete noun and should always be preceded by either a possessive noun, “a”, or “the” e.g. “Ethereum’s blockchain”, “a blockchain”, or “the blockchain”.
- Also, the native currency of Ethereum is “ether” or “ETH”.
Web3 is always capitalized and spelled as one word.
- Using “web3” or “Web 3.0” would be incorrect.
The abbreviation of “decentralized application” is “dapp”. Not “DApp”, “dApp”, or “Ðapp”.
- There is an ongoing debate over whether the term “decentralized application” is useful to begin with, at least in user-facing communications. In light of this, we should opt to refer to what we are building as “the Aragon client” (or “desktop and mobile client”) and use “app” to refer to the software that is used to extend the functionality of Aragon organizations e.g. “the Finance app”.
Always use an Oxford comma (“Note that a, b, and c are…”).
Lists should always be in alphabetical, numerical, or chronological order, unless there’s a good reason for them not to be.
The format to use for dates is either YYYY-MM-DD if numeric (e.g 2020-12-31) or Month D(D, YYYY) if spelled out (e.g. January 1 or December 31, 2020).
- Related: all times are communicated in UTC to avoid the confusion of “Daylight Savings Time”, which is inconsistently implemented across the world (even within the same country) and is generally a scourge on humanity.
About bullet points:
- Use a period (full stop) after every bullet point that is a sentence.
- Use a period after every bullet point that completes the introductory stem.
- Unless the bullet point only contains one word e.g. My favorite cryptoassets are:
- Use no punctuation after bullets that are fragment sentences and do not complete the stem.
- Use all sentences or all fragments, not a mixture.