Writing Style Guide

The writing style guide sets standards and processes for writing and reviewing official Arrow documents.

The goal of this guide is to help contributors improve readability and clarity of their publications to:

1. Ensure brand consistency across official publications
2. Attract more potential contributors
3. Reduce the friction involved in onboarding

💪 Motivation

Arrow DAO is an international effort. Although we conduct our business in English, our stakeholders vary in English fluency and reading proficiency. Even among native English speakers, confusion and misunderstandings arise when local idioms or slang are introduced.

In an attention economy, first impressions matter in forming long-term partnerships. The Arrow brand will benefit from consistent writing styles by presenting an accessible, professional, organized and committed front that attracts contributors and business partners.

📖 Guidelines

🔭 Scope

The style guide applies to all official and public-facing materials.

👥 International Audience

1. Reduce idioms, local slangs.
2. Units of measurement shall be in metric.
3. Timestamps shall be in Coordinated Universal Time (UTC) and use 24 Hour format (e.g. 14:00 instead of 2:00 PM).

♿ Accessibility

Some may access our contents using tools like screen readers. We want to be as inclusive as possible. Keep accessibility in mind when writing contents.

For rich media materials like images, always try to add descriptive alternative titles so that screen readers can parse the materials.

✅ Readability

Readability can be quantitatively measured by the Flesch-Kincaid score. To reach a broader audience without losing professionalism, we strive to score at which materials can be understood by 13-to-15-year-olds.

• If technology allows, take advantage of rich formatting like bold, italic, underline, ordered and unordered lists. We don’t want to throw a wall of text to our readers.
• Without losing meaning, reduce verbosity as much as possible.
• Avoid using jargon except for technical documentation.
• Spell out acronyms when first introduced.

🔎 Editorial Review Process

📃 Arrow Blog

1. The blog post submission must be in markdown format.

   1. A Pull Request must be made on the website GitHub repository.
   2. The new submission should be automatically broadcasted in Discord, and we do a fit screening.
   3. If any of the following fails, we stop here and reject the PR.

2. Prior to opening a Pull Request, please confirm the following about the piece:

   • Should not be an op-ed
   • Should not be irrelevant
   • Should not be identical to existing posts
   • Should not be promotional
   • Should have no spelling/grammar issues.

3. The "Editors" group on GitHub will review the blog.

4. Editors, at this step, are free to make stylistic edits as long as the meaning of the edited part remains unaltered. The goal is to make the writing more “Arrow-like”.

5. Review once again for inclusiveness purposes. Find out and modify wordings that might be too localized or exclusive. (don’t assume that everyone has the same context)

6. If it’s a technical blog, we need to review deeper for fact checks