mailchimp/content-style-guide

This is our company style guide. It helps us write clear and consistent content across teams and channels

content-style-guide's Issues

Suggestion on Race: https://styleguide.mailchimp.com/writing-about-people/

"At Mailchimp, when we write about a culture or ethnicity, we capitalize the name. For example, we capitalize Black as it refers to Americans in the African diaspora while we keep white lowercase since white refers to the color of a person’s skin and not a group of people."

The meaning of any word ultimately depends on its interpretation and usage, which can be highly subjective.
However, your description seems logically inconsistent.
Please refer to the second definition of 'black' and 'white' in the attached screenshots.

Resources Link broken on "Creating Structured Content" page

On the "Creating Structured Content" page/chapter, the link for the "Resources" page is missing/broken:

• broken link on the live site: https://styleguide.mailchimp.com/resources
• broken link as referenced within this repo: https://github.com/mailchimp/content-style-guide/blob/master/18-resources.html.md

Question - how are you displaying the pages on your website?

Hi! Thanks for: 1) writing this guide; 2) writing it all in Markdown so it is easy to edit; and 3) making it available under a CC license! It's quite an excellent guide!

This isn't an "issue" as much as a question - how are you creating the actual web pages that appear at http://styleguide.mailchimp.com/ ?

Are you running the set of md files through something to create HTML files? Are you using a web server that translates md files to HTML on the fly? Or doing something completely different?

I think it's great that you have the section at the end of CONTRIBUTING.md about 'Creating Your Own Style Guide", but I feel like this piece about putting the style guide pages on your own website is missing. If you could add something there - or perhaps point to a blog post where you explain how you did it - that would be very helpful for people who might want to adapt the guide.

Many thanks again for writing this and making it available!
Dan

In "Writing About People"

Hiya, Awesome MailChimp People!

First off, you all are wonderful! Thank you so much for this resource!

I edit a great blog by an #ActuallyAutistic SLP (speech language pathologist) whose clients are all littles on the spectrum. I am also in the same category (#ActuallyAutistic, not an SLP). As such, you might want to be aware that many, many of us detest person-first language. Some of us find it wonderful. But I've not met many of the latter. As a person with 'mental illness,' I can tell you the same rules apply as with other 'disabilities'. No matter who it is, or the thing they have limitations around - these same rules apply.

So, here are some thoughts on writing about people from the 'disabled' person's perspective:

It's best to check with the person you are writing about to find out how they prefer to be described. and then describe them that way consistently. Do not just use a style guide's instruction, which will cause you to ignore the actual person's needs and will damage your relationship with both that individual and their entire community. Yes, we do talk to each other and if your presentation of us in an interview goes against what we told you we were comfortable with to satisfy a style guide over a human being - we probably won't ever listen you, trust you, or read your work again. And we will tell others why.

For example, I am autistic. Not a person with autism. Saying I am a person with autism is as absurd as saying I'm a person with a brain, as though the brain (without which I will die) is somehow separate from me. I hope this helps clarify what person-first language sounds like to some of us out there reading blogs.

Always check with your subject as to how they want to be presented. It shows to your readers that you are really about that good relationship with them. It fosters trust in your blog, and your character. And you may find yourself on the receiving end of good press for your actual allyship to others, rather than for caving to the opinions of people who don't actually live the issues your blog is discussing.

In closing, I am beyond grateful for your hard work, folks! I hope you are not irritated by my comment here, but I want your principles, as stated in the intro, to really be felt by those who use your products. And this tiny change (advising to consult with your subject as to how they wish to be presented - person first or in some other manner) would prove to your minority readers and users that you MEAN EXACTLY WHAT YOU WROTE.

Thank you! Toad945

Broken parenthetical commas in grammar section

In the Grammar and Mechanics section, under the Slang and Jargon subsection, the following sentence has an unmatched parenthetical comma.

"One way we do this is with shards, or partitions that help us better horizontally scale our database infrastructure."

I believe it should be written:

"One way we do this is with shards, or partitions, that help us better horizontally scale our database infrastructure."

Nitpicky Issue with Grammar and Mechanics

This is regarding the specifics of the style guide rather than it's implementation using Markdown, so I'm hoping this is the still the right place to submit this.

First, I must say that I really appreciate this. My organization is is desperate need of a style guide, so I'm adapting much of yours for a first draft.

Specifically, I'm concerned about the section on Time. It's stated that time should be written with a space between digits and am or pm, but when time is written as a span of time, there are no spaces. Is this an oversight or intentional?

7am-10:20pm vs 7 am-10:30 pm

The second looks better to my eyes, but I also feel kind of silly pointing this out. I guess.

Thanks for your time in making this, it's very helpful

Missing 'is' in "Writing for Translation"

First off, I love this resource. Thank you so much!

I think there should be an 'is' in the first sentence here: https://github.com/mailchimp/content-style-guide/blob/master/13-writing-for-translation.html.md#consider-cultural-differences

MailChimp’s voice is conversational and informal.

Blog post link is broken in README

The link to the blog post redirects to https://mailchimp.com/developer/ instead of http://devs.mailchimp.com/blog/how-we-built-the-mailchimp-content-style-guide/

Directive to create the source code for your projects

I read the style guide with great interest. I think that the programmers have a style guide to create the source code. Is it possible this also to publish?