Content Guide

Content Design Guide

These are best practices for designing content. This advice won't necessarily translate well to more editorial content but should help when writing or updating any pages intended for life on the community-development platform.

Originally crafted with 💚 by Ryan Cordell

Pre- Publish Checklist

Removed/explained all acronyms
Removed any gendered pronouns
All titles are written in sentence case
No latin abbreviations
No metaphors

Images

All images/videos have alt text
Any text in images is also in text on the page

Explain

No knowledge is assumed
There are links or explanations to any specialist terms

Formatting and reading experience

All lists are formatted as bullet points rather than prose
Checked the reading age in hemingwayapp.com
All numbers are written out as numbers
Most links are at the end of sentences
All link copy describes the destination
Content is chunked up into small sections
Any unnecessary passive language has been made active

Note that emoji inline support is disabled for now. 😮 <- but you can insert them manually. 🤠

Emoji

Checked how the emojis render on different devices
Checked that you're not using culturally insensitive emojis
No emojis are used in place of words

Accessibility and inclusivity 🌈

Avoid acronyms

Acronyms require a certain level of knowledge making them exclusionary to new users. The Maker community should feel like an open community not a club.

Try and avoid acronyms
If it's unavoidable, like a page dedicated to Multi-collateral Dai, be sure to write it out in full the first time you use it: Multi-collateral Dai (MCD)

Avoid colloquialisms and metaphors

Colloquialisms and metaphors are also exclusionary as understanding may rely on being from the same local geography as the writer.

✅ Do

Apply for hackathon funding

❌ Don't

Apply for Hackathon Funding

Avoid "e.g.", "i.e." and other latin abbreviations

These aren't accessible as screen readers don't deal very well with them. Opt for phrases like "such as" or "like" instead of the abbreviations.

Avoid big words

Another hangover of our schooling days is the tendency to try and sound clever by using big and fancy words. But you don't want your web copy to read like a Victorian author. Always question whether there is a simpler alternative in your writing.

✅ DO

Buy
Mix
Agree

❌ DON'T

Purchase
Amalgamation
Acquiesce

Avoid gendered pronouns

If you need to refer to a "his", "her" or "their", use "their" for the most inclusive content. This shouldn't come up too often if you're addressing the user as "you".

Explain 💬

Explain blockchainisms and financial jargon

It's fair to assume that some of the terminology on the site may be highly technical or require a lot of financial understanding. Don't assume that all users are familiar with this.

If a concept can't be explained using more familiar terminology, add an explanation or a link to an explanation

You can generate Dai using a vault. Vaults are a Maker product that allow you to deposit Eth and withdraw Dai.
You can generate Dai using a vault.

Explain images

If you're using an image that features text, like a process diagram ensure that the content is written in a machine-readable format. Screen readers can't detect words in an image and neither will search engines.

All images should also have alt text that describes the image.

Alt text: The Dai logo

Formatting and reading experience ✏️

Favor active language over passive language

"Generate Dai" vs "Dai can be generated"

💡 Tip: if you can add "by bitcoiners" to the end of a sentence and it still makes sense, it's probably passive...

Aim for a maximum reading age of: 9 (the lower the better)

Don't consider this as "dumbing down" your content. A lower reading age simply makes the reading experience more enjoyable and more efficient. Remember users haven't come to your site to experience your prose, they've come to complete a task or get information.

Pop your content in hemingwayapp.com to check its reading age and remove any unnecessary adverbs

Favour small chunks of content with clear headings

As mentioned above, users haven't come to your site to experience your prose, they've come to complete a task or get information. They'll likely scan your page looking for keywords related to their task. Short chunks of content with clear headings helps users scan.

Front load your headings. Aim to give the user information they need in the heading rather than just signal that the information they need might be in that section.

"Apply to grants@makerdao.com" not "How to apply"
Notice how this document has been structured to front-load the titles

Make sure links describe the destination

Avoid vague link text like "learn more". It's more helpful to set the user's expectations around where the link will take them.

✅ DO

Meetup promotion guide

❌ DON'T

Find out more

Avoid links mid-text where possible

This makes content harder to scan and can be problematic for autistic users.

✅ DO

We'll show you how to promote your meetup in our Meetup promotion guide

❌ DON'T

Read the Meetup promotion guide to find out how to promote your meetup.

Use bullet points to split up long paragraphs/lists

Bullet point lists are a great format for parsing list information. Don't write out lists in paragraph format as it makes content far easier to miss.

✅ Do

You'll need to be familiar with:

GitHub
Markdown
Maker
Google docs

❌ DON'T

You'll need to be familiar with GitHub, Markdown, Maker and Google docs.

Use numerals

It's often thought that you should spell out numbers under 10. However, writing all numbers as numerals is better for scan readers.

✅ Do

Ryan has made 5 contributions

❌ DON'T

yan has made five contributions

Emojis 🤪

Emojis should support not replace words

For example: don't use a money emoji (💰 ) instead of saying money.

Consider cultural implications

That friendly thumbs up emoji ( 👍 ) can actually be rude in middle eastern culture (and other places) – it means "up yours!". Another example might be the plate and cutlery emoji ( 🍽 ) which naturally biases western culture.

Check how they look on all devices

Some emojis are unrecognizable on certain devices.

Are you referring to cookies or crackers?

Are you referring to a friendly detective or a shady stalker?