Call for Feedback on Tone and Voice Guide

Welcome to the official home of the WordPress Documentation Team.

This team is responsible for coordinating all documentation initiatives around WordPress, including the handbooks and other general wordsmithing across the WordPress project.

Want to get involved?

Start here to find out more about what we do and how to contribute:

Onboarding to Documentation Team: An overview of what we do and how to collaborate
Documentation Issue Tracker on GitHub: Submit any Documentation Team-related issues on GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/

Weekly meetings

Join our discussions of documentation issues here on the blog and on Slack.

The documentation team holds weekly office hours and monthly Contributor Days on each Tuesday of the month in the #docs SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. channel. It’s also where you can contact the team at any time outside meetings.

Marcus Kazmierczak 11:04 pm on January 16, 2019

This is great and glad to get it documented, thanks @kadair

The good/bad examples really help clarify, I think you could add more of them if you have them.

The biggest difference I see between the User and Developer documentation is the technical nature, which you called out. One point in assuming technical knowledge is to try to specify, when applicable, what knowledge is being assumed. For example, in tutorials I try to say up front what knowledge is assumed and a link to where a person could get up to speed for that knowledge.
- Kate Adair Bartolo 3:45 am on January 27, 2019
  
  Thanks, @mkaz. I will think of a few more examples to help with clarification. I’ll also add the point about specifying what technical knowledge is assumed. I think that would be especially helpful since there can be a broad range of technical knowledge required in both user and developer docs. It could also justify a more technical tone.
Naoko Takano 4:11 am on January 21, 2019
I think including an emphasis to consistency could be helpful for translation. From a translator’s standpoint, inconsistent use of terms and expression can be confusing.
Also, unnecessarily long or fancy paragraphs can cause mistranslation. Writing concisely is mentioned a couple of times, but maybe referring that the docs will be translated could help?

Are you planning to add a section or separate page on how to handle formatting of various contents? For example, Codex articles have different ways of referring to dashboard navigation (e.g. “Menu 1” > “Screen 1”, Menu 1 → Screen 1). I’d love it if those are consistent.

Other examples:
- Some use “log in” and others say “sign-in”, “login”
- “Press the button”, “Click the button”, “Click XXX”, “Hit XXX”
At work, I shared a blog post called 16 Rules of Effective UX Writing as a good resource for writing better for translation in mind. It also has good bits about writing docs, so I highly recommend checking it out 🙂
- Kate Adair Bartolo 10:36 am on February 4, 2019
  
  Hi @nao, I’m also working on a grammar and style guide, which will have a detailed section on formatting consistency (like the dashboard navigation example you gave). I’ll mention consistency in the tone & voice guide as well though. Thanks!
  - Naoko Takano 6:27 am on February 5, 2019
    
    Sounds great! Looking forward to it 🙂 Polyglot locale teams will be able to use the formatting doc to study & incorporate into their translation style guide too.
Tor-Bjorn Fjellner 7:33 am on January 21, 2019

Perhaps would be good to clarify that these pieces of advice concern the use of English? And that many translation locales have their own style guides ( https://make.wordpress.org/polyglots/handbook/tools/glotpress-translate-wordpress-org/list-of-glossaries-per-locale/ ) and that some locales even maintain more than one variant. (in most cases a providing a choice between formal and informal addressing.

Regarding “contractions” – please add a clarification: “In English, we use contractions (I’m, don’t)”

Perhaps also good to mention that the system for translation handling will always regard the strings shown by the code as en_US, i.e. English (US). In other words, whenever in doubt, use U.S. spelling for text in code that is shown to the user or visitor.
Tor-Bjorn Fjellner 7:45 am on January 21, 2019

One more thing: Bear in mind, that many cultural references are more or less limited to certain regions. For example, many people outside of the U.S. don’t know what “Super Bowl” means, or how baseball is played.
Pascal Casier 9:53 am on January 21, 2019

As Nao already pointed out, it might be good to add a note on keeping in mind that the original English document might be translated into lots of other languages. Next to the consistency (which is indeed number 1 also on my list), the use of standard plain English is really preferred.
It would not be the first time that I join discussions in the Dutch or French local slacks trying to ‘guess’ what certain expressions would mean in the specific context.
Although I don’t like written texts like ” y’know “, at least we can still understand them. But when it gets to “dotted Is, crossed Ts” or expressions like “This is a stub”, discussions start all over polyglots land 🙂
Xavi Ivars 6:36 am on January 23, 2019

I’m supportive of making it clear it’s an English-centric guide. For example, when it talks about using the second person, in English it doesn’t matter if it’s singular or plural, but some other languages (French, Spanish, Catalan,… ) have different versions of that (2nd singular and plural, 2nd formal singular,…).
Kate Adair Bartolo 4:13 am on January 27, 2019

Thank you @nao, @xavivars, @casiepa, and @tobifjellner. It’s great to have feedback from the polyglots teamPolyglots Team Polyglots Team is a group of multilingual translators who work on translating plugins, themes, documentation, and front-facing marketing copy. https://make.wordpress.org/polyglots/teams/.! I’ll incorporate all your feedback into the guide and examples. You’ve made some very good points.

I believe we will leave the draft up for feedback for another week before finishing the guide. I’ve been on vacation but will be back next week to incorporate all feedback. 🙂
Milana Cap 4:12 pm on January 28, 2019

As part of HelpHub team and Serbian community I’d just like to emphasize everything already stated for localisation. Simple sentences in as official English as possible, with insisting on consistency is very much appreciated.

Also, +1 for examples. There can never be too many good/bad examples.
Joy 4:51 pm on January 28, 2019

It says the Tone should be “clear, concise, and very precise” and the Voice is “friendly and professional”.
Maybe what I am missing in the existing docs is amplification of friendly and clear, but in the form of context.
For User docs, the context of the thing being explained should be part of how you make it clear.
For Dev docs, the context of the how, when, why of the thing being explained should be part of how you make it clear and more helpful.

I know it says concise, but too concise leaves out context, and is not very helpful. Maybe context is as simple as a link to a related page, or one sentence stating how you get to this scenario.

Want to get involved?

Weekly meetings

Share this: