Style and Phrasing

Make each word count

As writer Frank Conroy once said, “The goal isn’t brevity for its own sake but clarity.” You don’t have limitless space. Make your words count.

Don’t use ten words if you can use five. “That” can generally be cut. Sometimes “with” or “of” can, too. Look out for filler terms like “at your fingertips” and cliché tech terms, like “disruptive”

  • Before: TYPO3 puts the support, flexibility, and features you need at your fingertips so you can start high-value projects quickly.
  • After: Launch projects quickly with TYPO3’s flexible, feature-rich Core and 24/7 support.
  • Before: TYPO3 is a CMS that has a developer focus
  • After: TYPO3 is a developer-focused CMS

Go light on adjectives. As a general rule: verb > noun > adjective. Verbs and nouns describe without going overboard.

  • Before: TYPO3’s streamlined, efficient, disruptive CMS is great and easy for busy, hard-working content editors.
  • After: TYPO3 CMS’s workflows and editing tools save content editors time.

Use active verbs often

Replace passive verbs with active verbs to clarify actions and meanings. Look out for “are,” “was,” and “be” followed by a past participle ending (often ending in “-ed.”)

Tip: Recognize passive constructions. They usually fail to mention “who” is acting, so you are left asking, “The action was done by whom?”

  • Before: A content element can be moved, copied for reuse, and deleted.
  • After: You can copy, reuse, move, and delete content elements.
  • Before: Once our solution was implemented ...
  • After: Once we implemented the solution ...

Gerunds. Check if gerunds (phrases that end in -ing) are weakening your message.

  • Before: “Creating an adequate content strategy template is a helpful tool for planning your content.”
  • After: Create a content strategy template to plan your content.

Replace helper verbs with more precise, active verbs. Look for “has”, “does”, “gives”, “stays”, or “keeps” + a noun for candidates.

  • Before: “TYPO3 gives marketers the tools they need to keep simplifying the many decisions they have to make on a daily basis.”
  • After: TYPO3’s tools simplify your marketing team’s daily decisions.

Be Specific

Use the most specific version of a word or phrase. Don’t generalize or be vague. Write about the technology or product at hand, rather than technology or the internet as a whole.

Highlight words unique to the product, company, or persona. If reading something in isolation, could it apply to any or many technologies? If yes, try to make it more specific to your subject.

  • Before: TYPO3 CMS was designed to support enterprises with the effective tools, systems, and frameworks they need.
  • After: TYPO3 CMS supports enterprises with a User Access Management system, 24/7 support teams, and centralized Digital Asset Management.

Watch out for filler words used in tech-speak, like “efficient”, “streamlined. ” Replace them with more specific, results-based phrases like “speeds up deployment” or “saves editors time.”

  • Before: Get streamlined workflows that are customizable for editors’ and publishers’ needs.
  • After: Customize workflows to match your internal editing and approval process.

Write professionally and clearly

Grammar, spelling, style, and tone should be professional and correct. Generally, you should try to adapt tone and style to the context, target, or channel.

Avoid overly casual language that sounds more conversational than written.

  • Before: TYPO3 makes really great stuff for developer-type people.
  • After: TYPO3 is made for developers.

But don’t be too stuffy… our friendly, open personality should still shine through.

  • Before: Review testimonials from our satisfied customers.
  • After: Hear from our satisfied customers.

Be positive. Rather than criticize competitors, frame the challenges that the product or organization is trying to solve—and highlight how they do it well. (We don’t do FUD or negative copy.)

  • Before: Many content management systems come with a high risk of security vulnerabilities. TYPO3 keeps your installation protected with advanced security practices upheld by a dedicated team, and a great developer experience, and a community of 500+ contributors to boot.
  • After: Keeping your website secure should always be top of mind. TYPO3 has industry-beating low numbers of vulnerabilities, and a dedicated, vigilant security team.

Be Compelling

Use interesting, bright verbs and nouns. OneLook Thesaurus is a great resource.

  • Before: TYPO3 helps agencies create digital value.
  • After: Agencies thrive when they use TYPO3.

Write headlines that grab attention. Try alliterations, varying rhythm, metaphors, etc.

  • Example Article Header Before:

    • The Product X feature set focuses on community

  • Example Article Headers After:

    • Community-Focused Features: The Product X story
    • The (funded) future of Product X

Look for ideas and inspiration from around the web. Feel free to borrow sentence structures from well-known brands.

  • Example from Mailchimp: “Marketing smarts for big ideas.”
  • Similar sentence structure: “Security software for peace of mind.“

Bring prose to life with figurative language

Figurative language can add life, color, and depth of meaning to complex or dry concepts. It will express nuance or demonstrate real and tangible qualities that plainer language might struggle to convey. Some common examples are:

  • Simile: Saying something is like something else (e.g., “Computer Malware can spread like a virus.”)
  • Metaphor: Saying something is something else (e.g., “Malware is a virus that preys on software.”)
  • Analogy: Saying something is like something else to make an explanatory point. (e.g., “Not all malware is business-critical. Some malware is simply annoying and time-consuming, like a common cold is to the human body.”)

Technical writing is full of figurative language. Common phrases like computer bugs, patch releases, front-end caches all come from other references (in this case, illness, clothes mending, and storage) and help clarify meaning.

General Guidelines for figurative language

  • Language should be universally understood: Since much of our content is translated, we strive to use translatable, region-agnostic metaphors. Avoid cultural references, idioms, and colloquialisms that could be meaningless or offensive in other cultures—e.g., “He was a Benedict Arnold.”
  • Use figurative language to clarify complex concepts. Extended metaphors can help simplify concepts. Always explain the concept in real terms using plain language, either preceding or following the metaphor. Never rely solely on metaphors for understanding. (See this primer on containers for an example of an excellent extended analogy using “bricks and architects.”)

  • Use analogies to help make raw or dull data more interesting and help people visualize it. For example, (from chapter 19 of \"Everybody Writes\" by Ann Handley)

    • That's enough cable to go to the moon and back three times,
    • That's enough electricity to power the city of New York for a week.
  • Compare objects with natural connections or inherent similarities, like a garden and a customer base, that both grow: “Consistent customer communications are like watering your garden.”
  • Use metaphorical language sparingly: Too many or mixed metaphors can overwhelm readers and obfuscate rather than clarify. Try to limit yourself to one or two usages per article.
  • When in doubt, go with simple language. Not everything requires a metaphor, simile, or analogy. Use figurative language only when it adds life, color, or depth to your piece, never at the expense of clarity.

Use non-violent language

We aim to use non-violent language because:

  • We communicate to connect. Non-violent language helps create and strengthen connections. Violent language separates, categorizes, and destroys.
  • We focus on bringing value to customers by understanding their needs and solving their problems compellingly and uniquely. War metaphors are not only cliché and tired; they also reflect negative, outdated strategies (as outlined in this piece by Frank V. Cespedes, Stop Using Battle Metaphors in Your Company Strategy ).
  • Collaboration, creativity, and diversity are important for most organizations today. Culture is central to that, and a significant component of culture is how we communicate. Non-violent language helps immensely.

We use non-violent language by replacing metaphors around war with other, more peaceful, constructive ones like art, carpentry, and gardening. For inspiration, check out The Language of Peace: Constructing Non-Violent Metaphors , notes from a workshop by Dr. M.J. Hardman.

Examples

  • Before: head-to-head comparison
  • After: side-by-side comparison
  • Before: Translation support is a powerful weapon in your CMS arsenal.
  • After: Translation support is a powerful tool in your CMS toolkit.

Use inclusive language

Be inclusive. Our goal is to help readers feel respected and welcomed. Inclusive language demonstrates empathy for readers. Non-inclusive language shows prejudice, bias, discrimination, or a lack of sensitivity. And as we said under Use non-violent language , “We communicate to connect.” Non-violent language helps create and strengthen connections. Violent language separates, categorizes, and destroys.

Be respectful. Ask people you are writing about how they prefer to be identified and referred to. The UK National Institute for Health and Care Excellence has a comprehensive guide to using “person-centered” language in the Talking about people section of their style guide.

Pronouns. If you need to use pronouns throughout an article, balance the use of she/her with he/him. We prefer to use a majority of she/her instances. The singular “they” is also acceptable.

Remove Bias. We work to remove bias from our language. Inherent biases around gender, race, religion, body types, and other issues are often difficult to see in ourselves.

Address readers directly

Try to use “you” instead of “they” or the archetypal persona (e.g., “developers”).

The direct address makes people feel spoken to. Address your readers where it makes sense throughout a blog post.

  • Before: The direct address makes people feel spoken to.
  • After: Speak to your readers, address them directly.
  • Before: Developers like Technology X because it makes deployment easier for them.
  • After: Technology X will make your deployments easier.

Don’t criticize

Stay positive and constructive. If you don’t know your readers’ context or circumstances, you can’t tell them, “you’re doing it wrong.” Don’t tell them to be scared or worry. Likewise, don’t blame people for the software or systems they might have inherited along the way.

Highlight the helpful features of the product you’re promoting to describe a brighter future for your readers instead.

Focus on the product, not the person.

  • Before: Many developers get overwhelmed by system maintenance. Technology X minimizes maintenance issues, so it’s not so hard for you.
  • After: Complicated system maintenance hinders your development. Technology X minimizes maintenance issues, so that you can focus on your work.

Don’t write negative copy or FUD (fear, uncertainty, and doubt/disinformation)

  • Before (example from a podcast ad): “If you’re still using TECH X, you’re wasting your time.”
  • After (theoretical): “Switching to TECH Y, can double your deployment frequency, leaving you time to do other important things.” [Of course, we need to be able to prove that claim.]