Word Choice and Mechanics¶

Use technically accurate language¶

Accuracy is extremely important in all writing, but especially applies to writing about technology. Technical accuracy establishes your credibility with audiences who automatically filter out hyperbole-laden or inaccurate marketing materials.

Get help from subject-matter experts (SMEs). Conduct and capture interviews to ensure your material is as accurate as possible. Even if you quote an expert precisely, have someone check your work to ensure you’ve accurately conveyed their expertise—they may pick up on a slight fault that could otherwise undermine the credibility of your work. Make sure any code snippets are formatted correctly and run without error.

A common form of “marketing-driven” inaccuracy is making unsubstantiated claims.

• Don’t use phrases like “the best” or competitive comparisons that cannot be substantiated.

  • Before: TYPO3’s editing tools are better than other CMSs’.
  • After: TYPO3’s structured content and flexible workflows help editors get their tasks done.

• Use available evidence to back up your claims.

  • Before: TYPO3 has best-in-class security features. After: TYPO3 was ranked first among open source CMSs in addressing vulnerabilities by SecurityRankerTM.

Quote Subject Matter Experts directly¶

Quote your SME’s directly wherever possible—and have them review the content before publishing. Technical audiences are allergic to technical inaccuracies. Using the wrong term or technical context in a post can turn off developers to your whole offering. Quoting an SME directly saves you from having to know everything (about everything!). Your experts will help you make your content accurate.

Guidelines:

• Introduce your subject with their full name (or how they wish to be known).

  • Include their role, expertise, and experience to establish them as a Subject Matter Expert.
• Use quotation marks.
• Use present tense verbs: “Emma Bovary explains,” or, “says Emma Bovary.”
• After the first quote, use only the speaker’s first or last name (last names are more formal). Use your choice consistently throughout the article: “says Emma.”
• Punctuate inside the quotation marks.

TYPO3 has members around the world who speak many languages. Direct transcriptions of quotes can often be grammatically incorrect—even from native speakers. As a writer, you might feel reluctant to change someone’s quoted words. It’s okay to touch up the grammar, correct facts or names, and remove repetition or filler words. As a general rule, write down the speaker’s intent and meaning rather than exact transcriptions. Use change tracking, and check with the speaker to get their approval. Most people will be happy that you’ve preserved and highlighted the intent of their message.

Explain and decode jargon, abbreviations, and acronyms¶

Explain technical terms and describe technologies to make sure your audience (with potentially different levels of relevant experience) is on the same page as you. Define technical terms directly in the article—and every article you write on the topic (you don’t know where a new reader might jump in)—and link to other articles with deeper explanations where it makes sense. Below are a few examples:

• Quick/advanced: CSS files
• Longer/more helpful: Cascading style sheets (CSS) are the code files used to define the look and feel of websites.
• Quick/advanced: Kubernetes container orchestration
• Longer/more helpful: Kubernetes, a container technology for managing large numbers of applications in the cloud.

Use American spelling¶

We use American spelling in English-language communications. The choice helps us keep our writing clean and consistent—it’s neither better nor worse than other spellings.

Double-check your words’ meanings¶

Look up definitions (use the Merriam-Webster Dictionary). If you think of a word that doesn’t sound or look quite right, onelook.com has a great thesaurus with filters for syllables, syntax, and more.

Opt for Readability¶

Use tools to check readability, including Grammarly, Hemingway Editor, Simple English, and the Flesch Kincaid Calculator. Keep reading grade levels at or below the high school level for global accessibility and non-native English speakers.

Avoid regional or colorful language and idioms in favor of clarity. Pay attention to seasons, dates, and holidays with regional variations and use the most general term possible. Say what you mean.

• Before: Some managers can’t see the woods for the trees.
• After: Some managers are overly-focused on daily tasks.
• Before 1: The team knocked this project for six!
• Before 2: The team hit a home run on this project!
• After: The team had a massive success with this project!

Don’t date your content¶

Avoid using words or phrases that need context and go out-of-date. Your piece can become inaccurate or indecipherable to someone reading the piece in the future.

• Avoid: “this year,” “last week,” “recently,” “coming soon,” “this summer,” etc.
• Exception: When you need to place limits on the useful life of a post, for example, “Version 10.2 is new as of June 2021.”
• Nuance: “At the time of writing” can be helpful when describing a version, feature set, or similar.

Grammar Choices¶

By default, we follow the Chicago Manual of Style and Google Developer Documentation Style Guide. Exceptions and practices we want to highlight are listed below. There will always be exceptions and gray areas :-)

Dashes, hyphens and parentheses¶

Follow the spacing and application rules listed on Grammarly.

• Em-Dash (—): Use the em-dash as “super punctuation”, to introduce and separate clauses and words.

  • Many CMSs—TYPO3, Joomla!, Drupal, etc.—are open source.

• Hyphens (-): We use hyphens to connect and join words.

  • They are well-behaved.

• En-dashes: We use n-dashes without spaces around to mark from–to in a number series.

  • We get 50–60 new members per month.

No spaces around the em-dash? (Not a hard-and-fast rule.)

• Generally, no spaces. In body text, we prefer the “old school” use of em-dashes with no spaces between them and the surrounding text.
• However, this can lead to awkwardly long word clumps and formatting problems across different line widths in responsive designs, especially in page headers, taglines, or large-sized text.
• Add spaces around em-dashes to account for visual flow or line breaks in responsive design. And when you think it is the right thing to do.
• Use this power for good.

Use parentheses to define acronyms you’ll use later in the piece or for very short asides. If a full sentence works without them, don’t use parentheses. Try not to use too many in a single paragraph. Examples:

• We offer Extended Long-Term Support (ELTS) plans.
• State your opinion (even a strong one) without making universal claims.

Use the Oxford Comma¶

A comma placed before the final “and” or “or” in a list with three or more items is called a “serial comma” or “Oxford Comma” in English. While incorrect in some languages, they are helpful, add clarity, and are visually pleasing in English! Grammarly explains more about the Oxford Comma.

Titles and Headings¶

Buttons¶

Numbers¶

Write numbers using a dot (.) as the decimal separator and comma (,) as the thousands separator. In general, use a maximum of two decimals—the number of decimals used should reflect the texts need for accuracy.

• The Association has 12,481 members.
• That is 99.96% accurate.

You may omit the thousands separator for the numbers 1,000–9,999.

• The function nesting limit is set to 1000.

Include a zero before the decimal point in numbers less than one

• The difference is less than 0.5.

Numbers less than ten are spelled out unless they are dates or part of a list with larger values.

• I need at least five developers.
• Choose between the numbers 4, 42, and 64.
• There will be 5-12 participants.

Write very large integers (above 999,999) using American* million, billion, or trillion, replacing the last six, nine, or twelve digits.

• The file has more than 30 million lines.
• All three million TYPO3 users are geniuses.

• *American large numbers

  • 1,000,000 (10^6) one million
  • 1,000,000,000 (10^9) one billion
  • 1,000,000,000,000 (10^12) one trillion

Currency¶

Write currency values using the three-letter ISO code, followed by a space, followed by the value written according to our number style.

• The tickets cost EUR 1,000.
• We made a profit of exactly USD 25,060.17.

Use currency symbols like € and $ as a short form when appropriate. Place them before the value, with no space separating them:

• Purchase for just €1.

Dates¶

Writing about specific dates and times might be appropriate for personal communications or meeting planning, but try to be as clear as possible. No one wants to miss a deadline because of a simple miscommunication.

Always write the month name because dates written as numbers can confuse our international audience. We prefer the international date style: day, month, and year. Always write the year in four digits.

• 24 December 2018
• 12 Sep. 2009

You can build in redundancies, too.

• Before: “Can you manage that before the end of the day on 4/5?”
• After: “Can you manage that before 17:00 UK time next Tuesday, 5 April 2021?”

The more of the following you include, the clearer you get:

• Month as full name or three letters (as rendered by the PHP function date(M.): Jan., Feb., Mar., etc.
• Include the year in four digits
• Include the day of the week
• Use 24h time
• Specify the time zone

Quotes¶

Write exact quotes between double quotation marks. Write quotes within quotes in single quotation marks.

• “I felt great each time he said ‘I love TYPO3’—was it too good to be true?” Sara asked.

Place punctuation within quotation marks.

• “I love TYPO3,” he said enthusiastically.
• “Did you hear about the new release?” she asked.

Changes and omissions within quotes are designated [by brackets].

• He said he “had [no idea] why people said ‘hello’ all the […] time.”

For long quoted sections, we use indented block quotations without quotation marks. Place colons and semicolons outside of quotation marks.

• The poem goes:

Emphasis¶

Use italics for emphasis on single words or compound words.

Use Bold text to increase visibility on words, compound words, parts of sentences, and sentences.

Never use underlined text.

Examples:

• Becoming a member is very important.
• This year’s accounts are looking very good.
• This text is not underlined for emphasis.