Create a copywriting style guide

[matthawkins90]

Overview

Decred already has high quality branding and a good visual design style guide, as seen here:
https://decred.org/brand/
https://github.com/decred/dcrdesign/releases

However, there isn't a general reference for Decred copywriting. In my mind, there are 4 types of Decred copy:

1. Software Documentation (https://docs.decred.org/)
2. Developer Documentation (https://devdocs.decred.org/)
3. User Interface Copy
4. Marketing Copy

Each section should have a unified voice that reflects Decred as a whole. However, each section should have a unique tone for the different audiences and contexts. (For further reference, Mailchimp provides excellent distinction)

Why we need Copywriting Style Guides

Good Decred contributors shouldn't just write copy. They should be good designers too. They should study the content and decide the best way to present the information.

We want Decred to be well-designed, easy to use, a consistent experience for all. Since the Decred project is open source with numerous global contributors, there should be a standard reference to guide contributors towards consistency. This is especially helpful when contributors have their own writing styles or don't follow common methods. The software documentation particularly needs to be very carefully tailored towards real people with busy lives and various levels of technical understanding. It's not about dumbing content down, it's about communicating as clearly and concisely as possible. If it is possible to eliminate a word, do it.

In general, the documentation is already very good. However, there is still room for improvement, and with more eventual contributors, there should be a reference that sets a high bar for quality.

In this issue description, I don't want to do too much finger-pointing at examples, but here are a few examples I found where consistency could be improved:

Note: none of these examples are necessarily wrong. Perhaps merely inconsistent.

You: how to set up your Decred wallet
A user: ways a user can acquire Decred.
You: If you are an online merchant
Passive: The object is more important than the subject

• Blocks can be found, Transactions are chosen, Decred has been engineered, A proposal is submitted

Active: The subject is the one doing the action

• This guide offers, The miner loses, Tickets vote, Anyone may submit,

Unnecessary text: This page provides instructions for that.

Naming / Vocabulary

If you write the noun Decred by itself, do you mean:

Decred is a blockchain-based cryptocurrency
Decred is short for decentralized credit
A unit of the currency is called a decred (DCR)
Decred’s governance
Decred treasury
Decred holders
Decred community
Decred contractors
Decred developers
Decred projects
Decred software
Decred network

Context is obviously required, but it may be helpful to limit the terminology so that contributors don't start getting too creative with new ways to say the same thing.

Further, there should be a style guide which clarifies things like capitalization of nouns such as Decred Treasury or Decred treasury.

Rules specific to dcrdocs

• When / where / if HTML is allowed
• When and how to add images
• Where to get images approved by Decred designers
• Good rules for using URLs
• When to create new tutorials, and when to just add a reference to an external guide.
• How to use code blocks correctly (including which color-coded syntax highlighter we use)
• Rules for wrapping text
• Others?

Ideas for how to get started:

I don't want to reinvent the wheel. I just think it would be valuable to point contributors to a reference, and judge all submissions accordingly.

In doing some research for this issue, three style guides particularly stood out to me:

Shopify

Use Plain Language
Grammar and Mechanics
Writing Documentation
Vocabulary

From their license:

You may not use the Polaris Design Guidelines (i) to develop, test, or
distribute an external, stand-alone Application (“External Application”)
unless such External Application is not identical to and is dissimilar
and visually distinct from Shopify products and services (including
the internal administration page of a Shopify merchant store (“Shopify
Admin”)), as determined by Shopify in its sole discretion, (ii) to mislead
consumers as to Shopify’s sponsorship of, affiliation with, or endorsement
of you, your organization, or your Application, and (iii) for any purpose
not expressly permitted by this License Agreement.

IANAL, but since Decred (the External Application) is not identical to and is visually distinct from Shopify...

MailChimp

Their guide is truly amazing.

Voice and Tone
Grammar and Mechanics
Writing Technical Content
Other Style Guide help

From their license:

We invite you to use and adapt this style guide as you see fit.
It’s completely public and available under a Creative Commons Attribution-
NonCommercial 4.0 International license. All we ask is that you credit
Mailchimp.

The Economist

The first requirement of The Economist is that it should be readily understandable. Clarity of writing usually follows clarity of thought. So think what you want to say, then say it as simply as possible. Keep in mind George Orwell’s six elementary rules:

1. Never use a metaphor, simile or other figure of speech which you are used to seeing in print (see metaphors).
2. Never use a long word where a short one will do (see short words).
3. If it is possible to cut out a word, always cut it out (see unnecessary words).
4. Never use the passive where you can use the active (see grammar and syntax).
5. Never use a foreign phrase, a scientific word or a jargon word if you can think of an everyday English equivalent.
6. Break any of these rules sooner than say anything outright barbarous.

Readers are primarily interested in what you have to say. By the way in which you say it, you may encourage them either to read on or to give up.

Request for Action

I'm not a professional copywriter or a designer. I'm an engineer who appreciates good design and noticed that the Decred community hasn't formally set a standard.

Personally, I think the MailChimp style guide is incredible, and I think the easiest solution for Decred Copywriting Guides would be to point contributors directly to it, and then make amendments for things specific to Decred.

As a path forward, I think the community should peruse the style guides I listed here, determine if one is generally acceptable for Decred documentation, and then formalize that decision.

Then, make additions or clarifications to the style guide which are specific to the Decred audiences (Software Docs, Developer Docs, User Interface, or Marketing).

[xaur]

May be useful:

• A few common things we had to document for DJ to not thinkg about it every time: https://github.com/xaur/decred-news/blob/docs/guidelines.md#typography
• Settling on terms (may be outdated a bit): Names for concepts decredcommunity/issues#65