Update: Style Guide and Brand Book handbook page

[eidolonnight]

From @thetinyl

While helping with last month’s documentation sprint, I noticed an item around updating the Style Guide and Brand Book handbook page.

I’m very interested in learning more about how this was put together, and what updates might be needed. Especially the writing portion. I’m also curious about what opportunities there could be in expanding it further.

If anyone has insights to share, historical context, is already working on this, or is interested in working on this – I’d love to help out so let me know!

[nalininsbs]

Adding update from Marketing meeting June 23, 2022 @abhansnuk - suggested looking at the detailed information put together by zetaraffix on the design items and wapuu in the handbook. (She should have a mention on this handbook page too for her work on the design and branding). Suggested checking with @yvettesonneveld for some of the materials that were provided. Link to update https://wordpress.slack.com/team/U0T28QQKX

[thetinyl]

Long awaited update here:

I've been having some interesting conversations with some leadership folks and community members around how the WordPress voice is described (among other brand writing specifics). I started gathering all my notes together with the goal of helping flesh out the writing guidelines.

With the latest release, some of the project leadership folks I spoke to thought it would be helpful to update this writing guide more quickly, so I'll be publishing the updated handbook page soon.

Some opportunities I'm hoping this expanded guide will start to fill:

• Be even more specific about voice and tone (this feels like a challenge for a lot of folks to grasp, currently)
• Provide relevant and contextual examples
• Direct the style and formatting for marketing and communications efforts (outside of the Make Marketing blog)
• Be, in itself, an example of how writing on behalf of the WordPress brand should sound

Since this is a living document, contributions and edits will be really important to make sure it stays up to date and easy to understand for current and future contributors. I'm hoping more folks will be interested in helping steward the upkeep of this project as well.

[sereedmedia]

Super exciting! When do you expect to publish the revision?

[thetinyl]

When do you expect to publish the revision?

Sometime this week! 🎉

[nalininsbs]

Highlighted at the marketing team meeting on November 2, 2022 for latest and anything which Lauren is needing in terms of input from the team. Thank you @thetinyl

[thetinyl]

In light of what I mentioned above:

With the latest release, some of the project leadership folks I spoke to thought it would be helpful to update this writing guide more quickly

The style guide and brand book page has been updated!

With the discussions around short form video and expanding our need for content, the importance to have refreshed writing guidelines immediately available felt in line with the "ship then iterate" philosophy across the project.

Next steps

This is really just an attempt at getting a jumpstart on collaboration. It's a living document, and it absolutely needs more team input. Something I was trying to be careful about, was taking a selective approach to how much information is included. I'm mindful that having too much information might actually be less helpful, but I'm curious what others think.

As you look through it, here are some notes and questions that came up for me as thought-starters for improvements:

• Marketing Team visual identity: This information has been moved into a separate page.
• Accessibility and inclusivity: This is a personal shortcoming in terms of my frame of knowledge (I'm still trying to learn as much as I can). I know there are a lot of folks on our team who are both passionate about these topics and much more knowledgeable, so hope you can help flesh these aspects out where it makes the most sense.
• Formatting: The Make P2 blocks aren't the friendliest in terms of design or formatting for clarity. I know there's a lot of bullets. If anyone has thoughts around alternative formatting to make sure the guide is even easier to look through, that would be great for everyone!
• Glossary vs. index of terms: This version of the guide doesn't include a glossary. This is done on purpose since there seem to be other glossary-type projects on the go. What might be helpful though, is to include a kind of index of terms that come up more often in marketing/communications pieces, mostly to help with spelling and formatting (e.g. Site Editor should be capitalized, it should be "open source" without a hyphen, etc). This is something that a glossary can also accomplish, however, so not sure if it's still a duplication of efforts or not.
• Are there any really important pieces of guidance missing?
• Is the voice and tone section clear?

As mentioned earlier, I'm excited to collaborate with folks on stewarding this project and keeping it up to date. I'm also excited to start sharing it with the community in the hopes that more people will feel comfortable helping out with our team's marketing efforts!

[murillol]

Fantastic work @thetinyl ! Just tagging @nalininsbs and @abhansnuk especially for the Inclusive section in Voice and the Accessibility and Inclusivity section, as they have a ton of knowledge and are always sharing guidelines and tips around this.

In the Clear section in Voice, I have a thought but not sure if the right place to address it is the Handbook: sometimes abbreviations, acronyms and certain expressions are not easily understood by people whose first language isn't English, or aren't in the US. Could we add a line about being mindful of that, or is it kind of obvious especially with the next section saying "Write for everyone: across cultures.."?

[thetinyl]

...abbreviations, acronyms and certain expressions are not easily understood by people whose first language isn't English, or aren't in the US.

@murillol Thanks for pointing this out. I'm curious what others think, since I can definitely see it fitting into the handbook in the section you mentioned. It feels like a different kind of note, more around language use than cultural expression (thinking about the following section you mention). Is that what you're thinking as well?

[murillol]

yes that's what I was thinking @thetinyl !

[thetinyl]

@murillol I've been thinking about this a lot and here would be my suggestions based on our discussion:

For abbreviations/acronyms, I'm thinking of adding the following bolded line in the "Clear" section:

Clear Leave jargon, technical speak, and fancy words behind. Use abbreviations or acronyms that are universally understood. Keep sentences short. Let your audience understand your point as quickly and effortlessly as possible.

For expressions, I'm thinking of adding the following bolded line in the "Inclusive" section:

Inclusive Write for everyone: across cultures, experiences, and identities. Help your audience feel included with language that doesn’t depend on cultural context. Be mindful of using expressions that are difficult to translate, or aren’t globally recognized. Humor, in particular, is best avoided as it’s often regional.

What do you think?

[nalininsbs]

I have spoken with Abha as @murillol suggested as she is away from the project part of this week. Thank you @thetinyl for incorporating the phrase we use about translation and global recognition.

Under inclusion, we may need a way to raise awareness about using phrases that may be inappropriate in terms of to mental health and different thinking approaches inclusion.

I wonder if we should also add something about holidays and festivals? It can get assumed that festivals in the US are understood globally. Eg Thanksgiving.

You may have captured this from previous updates: times should be in UTC as it is a global project.

In terms of humor, I would not say it should be avoided totally if this handbook is for internal communication too. It may rule out an extensive part of positive communication too inadvertently. Humor using context or language that is regional specific would be better to avoid.

Thank you for your efforts on updating this guide.

[thetinyl]

Thanks for these suggestions @nalininsbs!

raise awareness about using phrases that may be inappropriate in terms of to mental health and different thinking approaches inclusion.

I appreciate you bringing this up. I'm wondering if you have more specific recommendations in mind around this type of language. Are there resources/references available we should link to?

I wonder if we should also add something about holidays and festivals? It can get assumed that festivals in the US are understood globally. Eg Thanksgiving.

Is this something you've noticed a lot of in our external communications? If so, I'm hoping that having generally added more clarity around the Voice/Tone/global nature of the project will help here.

times should be in UTC as it is a global project.

Absolutely! I can update this.

In terms of humor, I would not say it should be avoided totally if this handbook is for internal communication too.

This brand writing guide is mostly for marketing and communications materials. If it can help guide new contributors in how they approach their language within the project as well, that's a happy by-product, but not the intent. In my experience, humor can be challenging for folks to get right (especially when it's written). In my experience, it's easier to say to avoid it (at least for external communications) than to add more guidelines around its use that could be easily misunderstood.

[thetinyl]

Recent updates to the guide include:

• Added language around abbreviations/acronyms in "Clear" part of Voice section
• Added language around expressions in "Inclusive" part of Voice section
• Added guidelines around UTC time in Date, Time and Numbers section

[thetinyl]

Since the guide has been updated, I'm going to close this issue.

Any additional suggested updates can be opened as new issues.