Subject: Editorial Guidelines DRI: @Yves Do Last update: October 2021
Welcome to the Strapi Editorial Guide. Writing is the most common way we communicate with the Strapi community, clients, partners and companies. How we write shapes the way the community perceives us as an organization, so it's important to write using the Strapi voice, even if the tone may vary depending on the situation.
With every piece of content we publish, we aim to:
- Empower the community. We help the community understand Strapi by using a level of language accessible that informs them and encourages them to use Strapi for their projects.
- Support. We treat readers with consideration and empathy by giving them the exact information needed and the direction to learn more. We always assume good faith and don't forget that we are more knowledgeable about our solution and that users are not necessarily as experienced as we are.
- Speak truthfully. We avoid jargon, metaphors, and exaggeration and focus on clarity and real proven, data-driven or claims.
- Respect. Above all, the Strapi voice demonstrates our deep respect for our community of clients and users. Ultimately, Strapi exists because of them, so it’s important to keep their needs at the forefront of everything we do.
To do so, we make sure our content is:
- Informative. We always know well the topic we are writing about. We use clear, simple and informative words and sentences.
- Useful. With every piece of content, we start by asking ourselves: why our users should care? Who is going to read this? How do we solve a problem for them?
- Friendly. We are humans and write like humans. We make use of spoken language when writing just like in a face-to-face conversation, and adapt to who we write for and about.
When you'll write for Strapi, always keep in mind who is your audience, and who will be reading your writing. Strapi's audience is diverse, but we mainly communicate with a technical audience and want to show Strapi as a helper of Engineering, Marketing and Operations departments.
Our primary audience is developers at medium to large companies, product managers and content managers represent our secondary audience. C-levels and executives need to know about Strapi but will consume less content from us.
- The Strapi readers are busy. Go straight to the point. We want to help them solve their problems, meet their deadlines, or handle their projects. Be data-driven, but avoid claiming something that you can't prove. - Strapi's audience is composed of experts. They are developers, product managers, or engineers, and know the ecosystem they evolve in. Use the right wording, syntax and be precise & concise.
Personas we write for
- Enterprise Developer: primary target use of Strapi. The first person to get in touch with the repository, website, product, and documentation.
- IT Lead Secondary target of Strapi. Usually, the person is responsible for selecting the piece of software to use on a specific project.
- Executive: Person with budget authority, security and compliance concerns, and ROI obligations.
Checklist for shipping content
Voice and tone
Our brand personality is the foundation of the vision we have for our brand so that we speak with the same voice on every channel we use. We respect that the community is among many types of organizations, and is in contact with Strapi through a diverse set of channels.
Writing is one way we can bring Strapi values to life. And above all, our voice demonstrates our deep respect for Strapi's clients and users. Ultimately, Strapi exists thanks to the awesome community of clients and users, so it’s important we keep their needs at the forefront of our writing style.
These five following words, together, shape the spirit and energy we share, the design we showcase, and the voice we use.
Strapi's voice is friendly, supportive, accessible, professional, and empowering.
We use subtle, harmless humor & a conversational style to make content management a joyful venture. We don't take ourselves too seriously.
Strapi's voice is friendly.
We are humans and write like humans. We stick to simple American English but sometimes bend some rules in conversations and make wise use of emojis to show closeness and empathy.
🤓 Want to join the community?
⛔️ DONT's Join the community. Share ideas: GitHub - Forum News & Updates: Twitter - Blog
Why? With every piece of content we produce, we aim to bring our values to life and to demonstrate our deep respect for our clients and users. Strapi exists thanks to the awesome community that has been supporting us from the beginning and we want to show that we belong together with the utmost gratitude and respect.
Strapi's voice is supportive.
We always praise accomplishments made by the community. We actively listen to any remark and offer solutions.
Great job Marc, thanks for your contribution!
Super useful, especially the image upload mutations. We will share it on our social media channels and keep it for further reference.
⛔️ DONT's - "Please refer to documentation", - "Please make sure to have a look at the documentation where everything regarding to your issue is mentioned" - Add a simple like or reaction to a user post. - "I don't know, I'm sorry for that. Check with my teammate"
Strapi's voice is accessible.
We use clear and precise language. We avoid jargon and being too technical. Every specificity is explained.
Strapi's voice is professional.
We are generally committed and polite, but also straightforward and clear, as against to being boastful, using jargon, or beating around the bush.
Strapi is the most starred open-source Headless CMS. Strapi gives developers the freedom to use their favorite tools and frameworks while allowing editors to easily manage their content and distribute it anywhere.
⛔️ DONT's Strapi is the best headless CMS. It'll make your team do faster, better and safer. Plus, it's free! What did you expect??
Why? Strapi's customers are medium to large enterprise organizations. Writing with a serious & professional voice helps us be perceived as thought leaders in our ecosystem and be able to tackle any challenges our customers may face.
Strapi's voice is empowering.
We focus on the positive side of each situation, we find solutions and we help our readers.
Hello @willnode, great job! Did you know that on our documentation you have a step-by-step guide to help you get started with your project?
⛔️ DONT's Hello @willnode, we kindly disagree with you. We think you should use this solution.
Why? We as Strapi experts know which content is available, where to find it and how to solve their issues. We are available to guide
Guidelines - Do's and Don'ts
For editorial content
Let there be sparkles in your eyes. Communicate with passion. Be inspiring and imaginative.
Exclamation points. Use exclamation points to show excitement and passion. But too many are annoying. Never use more than one at a time. Never use exclamation points in failure messages or alerts. (and btw: exclamation points go inside quotation marks at the end of sentences).
Don't own the Strapi community. The community is not Strapi's. Use "the" instead of "our" when talking about the community. If using the term "the community" is not precise enough, use "the Strapi community".
Team-spirit. Don't use
Be humble and ambitious, not arrogant. Always put first the value for the users before the value for Strapi.
Be polite and gracious. Whatever the situation, the user on the other side is a user and must be respected. Always respond with good faith, assuming that what is said is true and said for a good reason. Ask for precision and prove your point with data if you are right. Don't lose time in pointless arguments.
Be specific. Avoid vague language. Cut the crap.
Focus on your content and create a hierarchy in your information. Structure your content from the main information to the details and make it easy to explore and read with paragraphs, bullet points, or sections depending on the format.
Use Sentence case for all titles and headings.
Use capitalization for:
- every feature: Repeatable Groups feature, Dynamic Zones feature.
- job titles: CPO, Frontend Developer
- Brands and companies: Stripe, Nuxt, Gatsby.
Don't use capitalization for:
- URL: strapi.io
- emails: email@example.com
Dates. Spell out months and use American date and time notation. [American over English].
Commas. When writing a list, use the Oxford comma.
- Yes: Yves loves his sisters, Patricia, and Toscane.
- No: Yves loves his sisters, Patricia and Toscane.
Be user-first. Write for everyone to understand you.
Be inclusive and gender-neutral. If the gender is unknown or irrelevant, use “they/them/their” as a singular pronoun. Use “he/him/his” and “she/her/her” pronouns as appropriate. Don’t use “one” as a pronoun. Avoid calling a group of people "guys." Don't call women "girls."
Abbreviations and acronyms. By default, don't use acronyms if your readers hypothetically won't understand them. If you repeatedly have to use a word that has a common acronym, spell it completely the first time you mention it and specify the acronym between parentheses. Then use the acronym. If an acronym is super known, like API, just use it.
Never criticize. Some people may be arguing, frustrated, and therefore saying negative things about Strapi. Negative feedback is feedback, so it's more important for Strapi to understand the user's frustration than to win an argument. The process for this type of situation is :
- Thank the user for their feedback.
- Document the issue if relevant (GitHub Issue).
- Point the user towards the right information, if available, to help them.
- Continue the discussion.
Use active voice. We are makers therefore we communicate actively. Avoid passive voice.
Use contractions. We're careful writing with a friendly tone, and at being close to the Strapi community.
Use emoji. Emojis are a great way to convey emotion to your words. Use them sparingly though, and mainly in the title as bullet points or on social media.
Write positively. Avoid using negative sentences, by looking for words like "can't/don't" and trying to them against positive words.
Be playful. We use slang and urban language, but sparingly and in a natural way.
Huge congrats, give us a shout!
Responding to social media is everyone's responsibility. Everyone is entitled to respond to social media. When someone doesn't know the information, they should ask the relevant person to reply, either with the Strapi account or their personal account.
Continue conversation. Always try to get feedback from the user. Ending a conversation by liking, upvoting is not enough. The best option is to give meaningful answers and ask questions.
Show you're a Strapi team member. If you comment on social media (Hacker News, Reddit, Twitter, etc.) your profile should mention that you work at Strapi. By mentioning that you work at Strapi your comment will be more considered.
There is no need to mention it all the time as it could be irritating. A subtle disclosure is possible by speaking in
we form (we shipped, we messed up, we will make that, our product).
Don't put your ego first. Remember that you represent Strapi, its culture, and its values. This must be a priority before winning any argument. The goal is never to win an argument but to represent Strapi and help our community.
Any specific term used by Strapi should be defined in the Glossary.