Documentation Content Style Guide

#Mailchimp’s Content Style Guide

We've decided to take a leaf out of Mailchimp’s exceptional style guide. It serves as a great basis for everything regarding tone and language and offers good approaches for communication.

In some ways, though, the Neos documentation, as a technical guideline and instructional manual, will have to differ. One such example is Mailchimp's suggested word list which we've had to customize to our needs and our very own language denylist. You can find both below.

The following is taken directly from the TL;DR of Mailchimp's Content Style Guide.

#TL;DR

The Mailchimp Content Style Guide goes into depth on many subjects. It may be more information than you need. Here are the most important things to know.

Principles

Good content is:

  • Appropriate
  • Friendly
  • Useful
  • Clear

Voice and tone

Mailchimp’s voice is:

  • Straightforward
  • Friendly
  • Familiar
  • Human

Our tone changes depending on the situation, but it's generally informal. We have a sense of humor, but we value clarity over entertainment.

Our priorities are to educate our users about our products without patronizing or confusing them, so they can get their work done and get on with their lives.

#Word List

The spelling and capitalization are tricky and sometimes up for discussion. In an attempt to abbreviate this, we've compiled the following list:

  • node, but NodeType
  • Fusion and Fluid – both capitalized
  • AFX – all caps
  • FlowQuery – upper camel case
  • Fusion prototypes

Some words can be spelled a variety of ways and the internet will most probably agree on one or even two distinct spellings. We've agreed on the following

  • website
  • email

#Language Denylist

  1. Bleeding edge, cutting edge, next generation and anything else, that will be outdated in a few months time. The code, concept or approach might be new and fancy now, but in a few months time, that will likely have changed and the documentation aims to have a longer half-life than that.
  2. Try to avoid sounding like a sales person. The Neos community values sincerity and genuineness. We all know that code will have bugs and no software solves all the problems in the world. Don't make it sound like it will.