Editing Framework
Purpose of the Editing Role
BanklessDAO Writers Guild editors bring consistency, clarity, and cohesion to all written material published via the DAO’s communication channels.
We aim to retain the diversity and range of our writers’ voices while applying high standards of accuracy to all written content.
As an editor, you are the support coach for our writers. Make their voice as clear as possible. Light them up with comments, make "in-line" suggestions. Ask questions and provide possible solutions. In short, be involved with both the writer and the written word..
Purpose of the Editing Framework
This framework is provided as a guide for editors to achieve consistency in aspects of writing such as grammar, spelling, punctuation, usage, and accessibility.
In addition, Writers Guild members have agreed on best practices in relation to clarity of meaning, audience engagement through tone, and attribution of others’ work.
This framework is intended to be a living document and your feedback is welcome.
The pursuit of concise, relevant, informative, entertaining, thought-provoking, and overall excellent writing is a journey we are happy to take with you at BanklessDAO Writers Guild.
Content Overview
Clarity
Sentence clarity helps readers follow and understand the concepts presented. Clarity is achieved by focusing on the key message throughout. This section covers techniques to maximise readability and comprehension.
Voice and tone
Appropriate use of voice and tone will increase the connection between writer and reader. Keep the intended audience in mind and use inclusive language to convey meaning. This section includes some aspects to consider.
Grammar and usage
There are some regional or generational differences of opinion about correct grammar and the expression of information such as dates. This section provides guidance on Writers Guild’s accepted style, but we acknowledge that other style guides may specify different rules.
Spelling and punctuation
There are some regional differences in spelling and use of punctuation such as quotation marks. There are a range of opinions on use of the serial (Oxford) comma. This section provides guidance on Writers Guild’s accepted style, but we acknowledge that other style guides may specify different rules.
Images
Illustrations, charts, diagrams, maps, and photographs can add impact and interest to a written work. This section gives tips on accessibility, attribution, and logical flow.
Further resources
This section lists resources which have been useful in the development of this Writers Guild framework.
Clarity
Use plain, concise language
Use the simplest form of a word to express the concept. For example, in most cases, the word “utilize” is unnecessary; “use” will convey the same meaning.
Concise language enhances readability. Eliminate unnecessary phrases such as "in order to," "seem to be," and "in conclusion."
Avoid jargon
Use of jargon and crypto-native terms should be avoided if possible, but this is a challenge given the subject matter published by the DAO.
Where such terms are used, provide definitions and aim for consistency in capitalisation and punctuation. Some examples are given in Commonly used terms below.
Vary sentence length and aim for coherence
Shorter sentences are easier to read, but longer sentences can sometimes be useful.
Regardless, aim for coherence in the presentation of ideas and try to minimise the reader’s cognitive load.
Use parallel structures
Parallelism is the repetition of form and structure when including a list of items or ideas within a sentence. It serves to orient the reader to the connections between the various parts of the sentence and provides consistency.
Purdue Online Writing Lab provides some good examples, including this one:
Not Parallel: Mary likes hiking, swimming, and to ride a bicycle.
Parallel: Mary likes hiking, swimming, and riding a bicycle.
Express information using affirmative rather than negative
Expressing ideas in an affirmative way is preferred, unless the intention is to emphasize the negative. Affirmative sentences are usually shorter and easier for readers to comprehend.
Affirmative: Mary prefers riding a bicycle to running.
Negative: Mary likes riding a bicycle but doesn’t like running.
Affirmative: Mary rarely listens to the radio.
Negative: Mary doesn’t listen to the radio very often.
In some cases it might be relevant to put the emphasis on the negative, for example, I really don’t want to use that protocol instead of I prefer to use other protocols.
Choose past, present, or future tense as appropriate
Documentation should be written in the present tense, unless future tense is appropriate.
Past tense should be used when recording notes for Community Calls and the like. Regardless, be consistent with tense.
Past tense: The Guild members voted on the proposal.
Present tense: The Guild members vote on the proposal.
Future tense: The Guild members will vote on the proposal.
Voice and tone
Identify the purpose and adjust tone accordingly
Texts have a purpose: to inform, teach, entertain, persuade, or provide a call to action.
Persuasive writing will have a different tone to that of educational or informative text. Whereas a persuasive piece or a call to action will require authoritative language, the tone for an informative piece can be quite conversational.
Conversational tone: It’s worth checking the URL before signing the transaction. Hey don’t forget this step!
Persuasive tone: You must make sure you check the URL before you sign any transaction.
Identify target audience and define terms accordingly
Each article should have a target audience, and terms should be defined according to the familiarity with subject matter. For example, if the audience is already associated with a particular DAO, it’s not necessary to define terms that relate to that DAO’s operations. If in doubt, it doesn’t hurt to include a hyperlink to a decent definition or information page.
More on terminology and definitions
Beginner articles should limit the use of crypto-native terms — meaning terms or acronyms that originated within the cryptocurrency space such as WAGMI, HODL, "to the moon", etc.. We want to ensure that we are not over-exposing new/beginning readers to many unfamiliar terms at once.
Previously defined terms should not be defined in higher-tier articles. Higher-level audiences are expected to know the lower level terms and thus these terms do not need to be defined. It may still be necessary to define technical terms for this audience.
Where technical jargon and crypto-native terms arise, the following guidelines should be adhered to:
- Use of jargon and crypto-native terms should be avoided or explained.
- When use of jargon or crypto-native terms are preferred, these should be clearly defined when they are first mentioned to reduce confusion in the rest of the work.
- Crypto-native terms and phrases should be defined according to the following hierarchy:
a] Define in-line
Can the term or phrase be defined in a short sentence? If so, it should be defined immediately using hyperlink or text. A hyperlink to another page or article that best captures the essence of the context in which the term or phrase is used is preferred but an explanation in the text is sometimes more appropriate.
DAOs make use of multisigs (multiple signature wallets) and this means that....
DAOs make use of multisigs (multiple signature wallets), which are wallets that have multiple signers that require a majority to approve transactions. This means that....
b] Define in a footnote
If the term or phrase requires more than a short sentence, the definition should be expanded in a footnote for clarity with an included link to an expository article. Prioritise links to articles written and produced by BanklessDAO and/or Bankless LLC where relevant.
Use inclusive language
Language relating to aspects such as age, ability, gender identity, socioeconomic status, ethnic and cultural background should be inclusive and respectful.
Some key principles:
- A person is not defined by a characteristic. Mention characteristics only when they are relevant and put the person first.
“A person with low vision will probably use a screen reader” instead of “A blind person will probably use a screen reader.”
- Gender neutral language and pronouns are inclusive, particularly in situations where it is not possible to check a person’s preference.
Use “they” in place of “he”, “she”, “him” or “her”.
- Avoid using terms such as “guys” to address a group or gender-specific language to describe processes, such as “grandfather clause” or “man the phones”.
Use active voice instead of passive voice in most cases
Active voice clearly associates the subject of a sentence with the action they are doing, whereas passive voice removes this connection, making the subject a recipient of the action.
In most cases active voice will be more concise and easier to read, but passive voice can be useful to place emphasis on the action rather than who completed it (see the second example below).
Active voice: Congress passed the Bill today.
Passive voice: The Bill was passed by Congress today.
Passive voice: The hack was discovered by the operations team.
Active voice: The operations team discovered the hack.
Purdue Online Writing Lab provides some more great examples of active and passive voice.
Choose first, second, or third person plural voice as appropriate
When the writer is describing a personal experience or expressing their opinion, first person should be used, i.e. “I”.
When the material is regarding BanklessDAO and/or representing those of us within the DAO, voice should be in the first person plural, i.e. "We."
When addressing clients and users, voice should be in the second person, i.e. "You." This is particularly useful in instructional material.
When referring to any person or entity outside of the DAO, voice should be in the third person plural, i.e. "They."
Grammar and usage
Numbers
Numbers one through nine are written as words, and numbers over nine are written with their numerical representation.
Exceptions to this are where the numeral forms part of a specific label such as Layer 2 or Season 6.
Avoid starting a sentence with a number, but if this is unavoidable use the words rather than numerals.
There are three ways you can get involved.
We had 15 people apply for the role.
Fifteen hundred tokens have disappeared.
Use a comma separator when expressing the numbers 1,000 or higher using numerals.
Dates and times
For clarity, write dates in full. If abbreviation is necessary, include the month written as a three-letter abbreviation.
Do not use letters with the date i.e. 1st, 6th, 22nd.
The first example is the preferred style, but sometimes variations are more appropriate. Exercise judgement but stay with month, date, year format.
September 22, 2022
Sep 22, 2016
Monday, June 6, 2022
Don’t use an apostrophe when describing decades: 1990s not 1990’s.
Express times using 24hr clock and use the UTC time zone as a minimum (unless another time zone is more relevant to the point). Add others if appropriate but keep UTC.
The event is at 11:00 UTC on Sunday, March 6, 2022.
The workshop is scheduled for 14:00 UTC on March 16, 2022.
Percentages
Percentage should be expressed using numerals followed by the % symbol, unless used at the beginning of a sentence.
Try to avoid starting a sentence with a percentage, but if this is unavoidable spell it out .
We recorded a 53% increase in participation.
Fifty-three percent of owners voted for the proposal.
Measurements
We are writing for a global audience. Always include the unit of measurement when expressing temperature, distance, time, currency etc.
When using the abbreviations ‘k’ to stand for thousands, ensure this is lower case e.g. The budget is 100k BANK.
How to format commonly used terms
- BanklessDAO
- bDAO
- BANK (not $BANK)
- Community Call
- Snapshot
- web3
- TradFi
- DeFi
- token holder
- Layer 2
- crypto-legal
- cryptoasset
- crypto lawyer
- side chain
- multisig
- cryptoverse
When describing actions that might take place on different devices, use "select" for activation, "deselect" to return the option to a neutral state
Use "Click, swipe, and tap" for differentiation and accessibility regarding devices.
Protocols, products, and tokens
Protocols should be spelled out and capitalized to differentiate the protocol from the token; i.e. Ethereum vs. ETH, Cosmos vs. ATOM, etc.
Do not use a $ symbol in front of a token.
When referring to Bitcoin or Ethereum tokens rather than networks, use lower case unless it starts the sentence.
On the Ethereum network, ether is used to pay transaction fees.
Check spacing and capitalization of product, DAO, and protocol names as these do not always follow language conventions.
Snapshot | SushiSwap | MakerDAO | PleasrDAO | MetaMask | Coinbase | she256 | MetaFactory | UltraSound Merch
There is no need to capitalize decentralized autonomous organization if it is spelled out.
Reserve currencies
Fiat currency should be denoted using ISO 4217 currency codes rather than symbols. There is no need to include both.
The three-letter code follows the amount.
500 USD, 1,000 AUD
Italics
Italics can be useful for delineating examples, or instructional text, and for adding emphasis, but avoid overuse.
Title capitalization
Use AP style capitalization for titles, as follows:
- Capitalize the first and the last word.
- Capitalize nouns, pronouns, adjectives, verbs (including phrasal verbs such as “play with”), adverbs, and subordinate conjunctions.
- Use lowercase for the second word in a compound modifier (e.g., Mid-year or On-site).
- Use lowercase for articles (a, an, the), coordinating conjunctions, and prepositions.
- Capitalize words with four or more letters (including conjunctions and prepositions).
- Capitalize the ‘to’ in an infinitive (e.g., I Want To Play Guitar).
This tool will provide AP capitalization for you: https://capitalizemytitle.com/style/AP/
Latin abbreviations
It will be up to the editor's discretion to determine if the Latin use is relevant and appropriate.
i.e. is an abbreviation for the phrase id est, which means "that is." I.e. is used to restate something said previously in order to clarify its meaning.
e.g. is short for exempli gratia, which means "for example." E.g. is used before an item or list of items that serve as examples for the previous statement.
Source: Merriam-Webster
List formatting
Bulleted lists where each line runs on from the lead-in sentence, should:
- begin with the same part of speech
- remain relatively brief
- start each option with lowercase
- end with a single punctuation mark.
Lists like the one above are known as fragmented lists. Always use a colon to introduce this list. Avoid commas or semicolons on each line; these add unnecessary clutter. In an example like this one, the bullet points serve as commas and the assumption is that all of the listed items are equally important.
Bulleted lists of stand alone options where some or all of the items might be relevant for the reader should follow the same conventions as above, except for capitalization. In this type of list, each option begins with a capitalized word.
An example of this type of list might be one which gives additional information to the reader:
- A list of protocols for the reader to check out
- A list of recommended resources
- Lists of people to follow on Twitter
- Options for getting involved.
Bulleted lists of lengthy text should use capitalization for the first word of each point, and end every point with punctuation.
This is an example:
Here are some ways to achieve this:
- Make guild funding dependant on active members, as per the discussion on Guilds as Professional Associations.
- Include a finance person on project rosters to do the actual budgeting, rather than having teams stacked with people that don’t know how or enjoy budgeting.
- Create more support/tooling for creating budgets, including templates and treasury guild support.
- Provide more clarity on the funding process, including some basic expectations around project validation.
Citation of sources and quoted material
Always link to a source when asserting ideas that did not originate with the author and are not accepted fact. If the evidence is not forthcoming, work with the author to remove the claim or adjust accordingly.
Regardless of whether a direct quote or paraphrasing is used to express another author’s ideas, attribution must be included.
Where possible, cite the work of other DAO members or BanklessDAO, linking to other relevant published articles or Twitter posts where appropriate.
Specificity of hyperlinks
Hyperlinks should be used to contextualize or define terms. Links should be specific, not general. For example, when referring to Uniswap from an analytics angle, link to Uniswap dashboards, not the app page. When referring to a specific mechanism in Uniswap, link to an appropriate blog post or docs page.
Remove tracking from hyperlinks
When copying a link from Twitter or newsletter or other promotional page, delete the extra string of characters that starts with the ? — for example when you copy a Twitter link using the share button it will look like this: https://twitter.com/banklessDAO/status/1625194602138374157?s=20&t=FSZpnWf1gzx5WbRRgUL5YA — the highlighted part should be deleted. It is tracking information so marketers can tell where the web traffic has come from. It’s neater and preserves privacy to delete this part. Always check the link still works after editing.
Likewise, if you share a link from a Substack newsletter, delete the part after the ? — https://banklessdao.substack.com/p/of-cypherpunks-and-crypto-predictions?utm_source=substack&utm_medium=email
That vs which
🚧 Section coming soon: please refer to https://owl.purdue.edu/owl/general_writing/grammar/that_vs_which.html
Spelling and punctuation
Regional differences
Differences in language should remain where the meaning and or context is clear. For example: honoured and honored are both valid, as are decentralised and decentralized, in their respective regions. If in doubt, the editing should conform to American English.
Hyphen, Em dash, En dash
🚧 Section coming soon: please refer to https://www.merriam-webster.com/words-at-play/em-dash-en-dash-how-to-use
Spacing
Use single spaces, not double spaces, after periods.
Do use a space either side of an em dash or en dash.
Don’t include a space either side of forward slash (/).
Commas (incl. Oxford comma)
Writers Guild considers the Oxford (serial) comma to be standard.
Sometimes, the serial comma is essential, other times it may seem excessive but use it anyway 🙂.
More information and examples for how to use commas is available here, (noting that this page gives advice to restrict the use of the Oxford comma).
Semicolons
Semicolons have two main uses.
One is to provide clarity in a sentence which includes a list of items using commas.
The second is to link two independent clauses into a compound sentence. Both parts of the linked sentence should be able to stand alone as separate sentences.
For breakfast I have coffee with milk; toast with honey, peanut butter, and jam; and a banana.
I eat breakfast with one eye on the clock; I’m often late for work.
Merriam Webster provides a great explanation of usage.
Apostrophes
Apostrophes are used to indicate possession, not plural forms of nouns. Apostrophes are also used to show that letters have been left out, for example: ‘isn’t’ is a contraction of ‘is not’.
Quotation marks
🚧 Section coming soon.
Images
Alt text
Include alternate text for images to accommodate screen reading software, even if it is just a simple description.
Captions
Captions should be placed underneath the image, centred and italicized.
Attribution
As with attribution in the text, images should also include attribution. Include a link to the source wherever available.
Image placement
Place images in logical sequence to support the text. In general, the image should follow the text explanation, rather than be placed before the related section.
Further resources
- Australian Standards for Editing Practice. (2nd ed, 2013). Institute of Professional Editors Limited. Retrieved from https://www.adelaide.edu.au/graduatecentre/system/files/media/documents/2019-06/thesis-editing-standards.pdf
- Grant, A. (2020, Nov 1). 25 Editing Tips for Tightening Your Copy (Plus an Editing Checklist). The Write Life. Retrieved from https://thewritelife.com/edit-your-copy/
- Lingard, L. (2022). Writing for the reader: Using reader expectation principles to maximize clarity. Perspectives on Medical Education. https://doi.org/10.1007/s40037-022-00708-w
- Lingard, L. (2015). Enlisting the power of the verb. Perspectives on Medical Education, 4(2), 53-54. https://doi.org/10.1007/s40037-015-0177-9
- Lingard, L. (2016). Get control of your commas. Perspectives on Medical Education, 5(1), 39-41. https://doi.org/10.1007/s40037-015-0248-y
- Lingard, L. (2017). Mastering the sentence. Perspectives on Medical Education, 6(1), 51-53. https://doi.org/10.1007/s40037-016-0315-z
- Lingard, L., & Watling, C. (2020). Beyond feedback: 11 tips for coaching writing. Perspectives on Medical Education, 9(6), 370-372. https://doi.org/10.1007/s40037-020-00630-z
- The Writing Lab & The OWL at Purdue. (2021.) General Writing Resources. Purdue University. Retrieved from https://owl.purdue.edu/owl/general_writing/index.html
- Watling, C. (2015). The power of parallel structure. Perspectives on Medical Education, 4(6), 329-330. https://doi.org/10.1007/s40037-015-0227-3
- Watling, C. (2016). The three ‘S’s of editing: story, structure, and style. Perspectives on Medical Education, 5(5), 300-302. https://doi.org/10.1007/s40037-016-0284-2
- Watling, C., & Lingard, L. (2019). Giving feedback on others’ writing. Perspectives on Medical Education, 8(1), 25-27. https://doi.org/10.1007/s40037-018-0492-z
- WebAIM: Writing Clearly and Simply. (2022). Retrieved from https://webaim.org/techniques/writing/
Avoiding Plagiarism
- The Writing Lab & The OWL at Purdue. (2021.) Frequently Asked Questions Regarding Plagiarism. Purdue University. Retrieved from https://owl.purdue.edu/owl/avoiding_plagiarism/plagiarism_faq.html
- Turnitin. (2022). The Plagiarism Spectrum. Retrieved from https://www.turnitin.com/infographics/the-plagiarism-spectrum-infographic