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. Hence, it's important to write using the Strapi voice, even if the tone may vary depending on the situation.
Writing Goals
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 necessary information and 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 claims.
- Respect. Above all, the Strapi voice demonstrates our deep respect for the Strapi 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 use spoken language when writing, just like in a face-to-face conversation, and adapt to who we write for and about.
Strapi's readers
When you write for Strapi, remember who your audience is 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 in the 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.
Personas we write for
- Developers: primary target use of Strapi. The first person to get in touch with the repository, website, product, and documentation.
- Content Managers: The end users of Strapi.
- Executive: Person with budget authority, security and compliance concerns, and Return On Investment obligations.
Checklist for shipping content
Voice and tone
Our brand personality is the foundation of our vision for our brand, so we speak with the same voice on every channel we use.
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 we must 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.
✅ DO's
🤓 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 demonstrate our deep respect for our clients and users. Strapi exists thanks to the awesome community 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.
✅ DO's
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"
Why?
Strapi's voice is accessible.
We use clear and precise language. We avoid jargon and being too technical. Every specificity is explained.
✅ DO's
⛔️ DONT's
Why?
Strapi's voice is professional.
We are generally committed and polite but also straightforward and clear, as against being boastful, using jargon, or beating around the bush.
✅ DO's
Strapi is the most starred open-source Headless CMS. Strapi allows developers to use their favorite tools and frameworks while allowing editors to manage their content and distribute it anywhere easily.
⛔️ 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.
✅ DO's
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 - Top 20 Do's and Don'ts
- 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 discussing the community. If "the community" is not precise enough, use "the Strapi community".
- Team-spirit. Don't use
I, preferwe. - Be humble and ambitious, not arrogant. Always put first the value for the users before the value for Strapi. 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.
- 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.
- 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.
- Capitalization.
- Strapi
- every feature: Repeatable Groups feature, Dynamic Zones feature.
- job titles: CPO, Frontend Developer
- Brands and companies: Stripe, Nuxt, Gatsby.
- URL: strapi.io
- emails: hi@strapi.io
Use Sentence case for all titles and headings. Use capitalization for:
Don't use capitalization for:
- 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. We avoid calling a group of people "guys." or "girls.” but prefer using
folks(or else)" 🙂 - Abbreviations and acronyms. 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 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 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 naturally and politely. 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 account.
- Continue conversation. Always try to get feedback from the user. Ending a conversation by liking, and 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
weform (we shipped, we messed up, we will make that, our product).
Glossary
Any specific term used by Strapi should be defined in the Glossary.