Eclipse Foundation Writing Style Guide
- Using This Guide
- Representing the Brand
- Telling the Story
- Style and Punctuation
- Abbreviations and Acronyms
- Business Entities
- Compound Words and Hyphenation
- Dashes and Slashes
- Date and Time
- Email, Website, and Social Media References
- Exclamation Marks
- Geographic Names
- Language and Spelling
- Names and Job Titles
- Numbers, Statistics, and Prices
- Periods, Colons, and Semicolons
- Quotation Marks
- Technical Standards
Using This Guide
Follow the rules in this document when writing any Eclipse Foundation marketing content for any medium. This document covers writing style only and is intended to be used in conjunction with the Eclipse Foundation:
- Editorial guidelines for each content type
- AP Stylebook
The intended audience for this document is anyone writing on behalf of the Eclipse Foundation or representing the brand to an external audience. This includes the following:
- Employees of the Eclipse Foundation
- Media members and third-party content developers
- Agencies producing content on behalf of the Eclipse Foundation
Representing the Brand
Write all content in American English following the spelling in the Merriam-Webster Dictionary. When two spellings are provided, use the first entry.
- Choose simple, precise words with the fewest meanings. Always ask yourself whether the word or phrase will be easily understood by readers who don’t have English as a first language.
- Never include colloquialisms or culturally specific references.
- Use universally understood terms. Avoid clichés, jargon, outdated expressions, and phrases that only industry insiders will understand.
- Avoid overused phrases and marketing hype.
Trademarks and Copyright
Please visit the Eclipse logo and Trademark Guidelines section of the Eclipse Foundation website for further details on trademark usage.
Always indicate Eclipse Foundation trademarks on first mention of the trademarked term, either ™ or ®. Subsequent mentions of the trademarked term in the same text do not need to have the trademark indicated.
Do not indicate other vendors’ trademarks in marketing content. It’s too easy to miss trademarks, mark them inconsistently across content types, or mark them incorrectly. Instead, include a general statement at the end of each piece of content, as shown below.
Use the copyright and trademark notation once on all originals and copies of a work. It should be placed somewhere on the document so as to give "reasonable notice of the claim of copyright."
Use the format: © 2020 Eclipse Foundation. All rights reserved.
The copyright year is always the year the content was first published, even if the content is updated in a subsequent year.
- © Copyright 2020, Eclipse Foundation. All Rights Reserved. The Eclipse Foundation word, logo, trademarks, and registered trademarks are trademarks of the Eclipse Foundation. All third-party product names, logos, and brands are property of their respective owners and are used for reference only, and the Eclipse Foundation makes no representation of ownership of these marks.
Tone and Voice
Write all Eclipse Foundation content in an authoritative and professional voice that reflects our experience and leadership in open source software but is not stuffy, old-fashioned, or arrogant.
The tone should be direct, informative, and helpful, but never condescending, patronizing, or overly casual:
- Always present the information from the audience point of view, even when positioning Eclipse Foundation projects and initiatives. The text should demonstrate thought leadership with an authoritative understanding of industry and customer needs and challenges.
- Use third-person writing style to identify the audience in the content and for more formal content, such as white papers.
- Use first-person writing style for calls to action, instructions for readers, and in more casual content, such as blogs and social media posts, after the audience has been identified.
Using Our Name
Always refer to the Eclipse Foundation by its full name, never as simply “Eclipse,” as this can cause confusion with the Eclipse IDE, which the developer community often refers to as Eclipse.
Avoid referring to the Eclipse Foundation as “the Foundation” in standalone references. However, if the Eclipse Foundation name is already well-established in the paragraph, it can be referred to as “the Foundation” in subsequent mentions within that paragraph to improve readability.
- Avoid using the Eclipse Foundation name in a possessive construction such as “The Eclipse Foundation’s … ”
- After first use, Eclipse Foundation can be replaced with we, us, or our.
- Only capitalize “the” in the Eclipse Foundation if it is at the beginning of a sentence.
Referring to Membership Levels
The Eclipse Foundation offers four levels of membership: Strategic, Contributing, Associate, and Committer. When referring to each membership level individually, the names should be capitalized. When referring to membership in general, the words “member” and “membership” should be lowercase.
- Eclipse Foundation membership provides certain benefits...
- Eclipse Foundation members gain access to…
- A Strategic Member of the Eclipse Foundation has access to...
Referring to Projects and Working Groups
The Eclipse Foundation hosts open source software projects and working groups. It also provides marketing, intellectual property, and support services to them. It does not develop open source software itself or manage projects.
To avoid the impression of ownership or control, refrain from using the following phrases:
- Eclipse Foundation projects
- Eclipse Foundation research projects
- Eclipse Foundation working groups
Instead use variations that more clearly indicate the relationships:
- Projects hosted at the Eclipse Foundation…
- Community projects at the Eclipse Foundation…
- The Eclipse Foundation is home to several working groups…
- Working groups at the Eclipse Foundation…
The open source software projects hosted at the Eclipse Foundation provide technologies that anyone can freely use to develop commercial products and solutions. The projects are not products or solutions themselves.
When referring to projects, always use the project’s formal name. The formal name starts with one of the Eclipse Foundation’s brands (e.g., “Eclipse”, “LocationTech”, or “Jakarta”), followed by the project’s distinctive name (e.g., “Eclipse Che”, “LocationTech GeoWave”, or “Jakarta Activation”). After the first use, the more informal nickname of the project can be used. For example, on the first use, the formal name “Eclipse Che” would be used, but “Che” can be used in all occurance thereafter.
The project page displays the formal name, along with other potentially useful information about the project.
There are some exceptions.
The original top level project is named “Eclipse”. When referring to it, we consistently call it the “Eclipse top level project”; though it is generally more likely that the writer should refer to the “Eclipse Platform” or “Eclipse JDT” subprojects. Note that “Eclipse JDT” is often used by the community as a synonym for “Eclipse IDE”.
The MicroProfile specification project is simply named “MicroProfile”. Generally, though, the writer will likely refer to the products of the project, including the “MicroProfile Specification” or “MicroProfile Config” specification.
When referring to the project and code that enables the Open VSX marketplace, use “Eclipse Open VSX.” When writing about the marketplace itself, use “Open VSX Registry.”
There are also some examples of projects with names that violate our naming standards. The EclipseLink project, which predates our application of strict naming guidelines, incorrectly concatenates the Eclipse brand with another word; we refer to this project simply as “EclipseLink” and not “Eclipse EclipseLink”.
Projects like the Eclipse Modeling Framework or Eclipse Communication Framework, for example, are commonly referred to by their acronyms, EMF and ECF. The first occurance of these project names should either use the complete name, or--should there be cause to use just the acronym--the acronym prepended with the brand (e.g., “Eclipse Modeling Framework” or “Eclipse EMF”).
When referring to working groups, include “Eclipse” only when it is an official part of the working group name. Note that several working groups do not include the Eclipse branding.
Capitalize the names of projects, unless the name is purposely lowercase.
- Eclipse Theia project
- Eclipse zenoh project
Capitalize the phrase “working group” when it is included in the working group name, but not when the concept is referred to in general.
- Eclipse IoT Working Group
- Jakarta EE Working Group
- openGENESIS Working Group
- The working groups hosted at the Eclipse Foundation…
Referring to Communities
Use the word community to refer to the different groups that are associated with the Eclipse Foundation:
- The Eclipse Foundation is a community.
- Each project and working group hosted at the Eclipse Foundation is also a community.
- Each Eclipse Foundation community provides benefits to the ecosystem related to that technology area.
- We invite the entire Eclipse Foundation community to…
- The Eclipse Hono community will be hosting…
- The Jakarta EE community delivers benefits to the Java ecosystem…
- The Eclipse Edge Native Working Group focuses on edge technologies for the IoT ecosystem…
Referring to People
Remember that there are different ways to refer to people associated with the Eclipse Foundation and projects hosted by the foundation.
The organizations and individuals who use the technologies are users.
The organizations and individuals who incorporate technologies in their own products and projects are adopters.
The developers who actively work on projects are contributors or committers.
The people who are involved in working groups are members of the working group.
Organizations that pay an annual fee to participate in the Eclipse Foundation are members of the Eclipse Foundation.
Two general terms are also used to refer to people:
- Consumers are the people who use open source software, the adopters.
- Producers are the developers who create and enhance open source software.
Telling the Story
The first step in telling any Eclipse Foundation story is to identify the target audience and understand why they will be interested in the topic. Depending on the content type, audiences for marketing content may include:
- Software developers
- Software architects and decision-makers
- Product owners
- Chief Technology Officers and other C-level executives
- Academics and researchers
- Eclipse Foundation members
- Staff at industry publications
- Industry analysts
Always tell the story from the audience perspective, not the Eclipse Foundation perspective:
- Instead of thinking, “what are all of the things I want to tell the audience?” think, “what is it the audience needs to know?”
- Present the information in the context of how the Eclipse Foundation helps the audience achieve its goals.
Organizing Content to Capture Attention
Most people will not take the time to read an entire piece of content, so it needs to be written in a way that allows them to skim the content and get the main messages.
Always start marketing content with the most important information for readers so they immediately understand why this story is relevant to them, similar to the way news items are presented. This writing style is called inverted pyramid, and it’s widely considered to be the optimal approach for marketing content.
To follow this style in Eclipse Foundation content, start by summarizing the main challenge, issue, or trend associated with the topic and what’s needed to address it. Start each section with a similar approach, summarizing the key messages for the section before expanding on them in detail.
Assume most people will stop reading after the first paragraph or two. This will help to identify the points that need to be made in the opening sentences. Imagine an editor deleting the content, sentence by sentence, from the bottom up to determine how to order the information.
Use the body of the content to expand on the key points made in the opening paragraph and to provide statistics, examples, and other proof points that support the points. Describing real-world scenarios is often a good way to capture readers’ attention and help them visualize how the topic affects them.
Incorporating SEO Keywords
All content provides an opportunity for search engine optimization (SEO) using keywords. Before writing, ask the marketing manager which keywords and phrases to focus on.
Always include keywords in the following elements when you write Eclipse Foundation content:
- Main headings and webpage titles
- Opening statements
Keep in mind the content is for humans, not for Google. Don’t sacrifice readability or clarity for the sake of keywords. Remember that using too many keywords too close together can actually lower the standing of your content in search results. To avoid this problem, use synonyms for keywords and be sure to include terms that help to put your keywords in context. This concept is called latent semantic indexing.
Depending on the project, you may also be asked to provide:
- Alt text for images
- Title tags
- Meta descriptions
Each of these text elements should also include keywords.
The marketing manager will work with the web team to ensure Eclipse Foundation URLs are short and include at least one keyword.
If you are unsure about how to incorporate SEO keywords, the marketing manager can provide additional guidance. There are also numerous resources available on the web, including this guide.
Writing Effective Headings
Use the main heading, section headings, and subheadings throughout the content to clearly convey the key messages in the story. Ideally, readers can scan only the headings and still grasp the storyline and the key messages associated with it.
- Open Source Collaboration Drives Faster, Lower-Cost Innovation to Increase Competitiveness
- Eclipse Foundation Open Source Communities Give European Organizations Crucial Advantages
- The Eclipse Sparkplug Protocol Augments MQTT With IIoT Interoperability Essentials
- Jakarta EE Adoption and Compatible Implementations Are on the Rise
When you’re finished writing the content, go back to the beginning and read only the headings to determine whether they adequately convey the storyline. If they don’t, you may need to add subheadings.
Avoid using questions to try to capture readers’ attention. Most readers will immediately answer the question in their head, which may stop them from reading on. When tempted to write a heading that asks a question, consider the potential answers and whether they could stop readers from continuing:
- I don’t care.
- That question doesn’t apply to me.
To encourage people to continue reading, reword the heading to emphasize the benefit for readers in the context of the story being told and avoid negative headings.
- Instead of “Why Is Open Source Software Gaining Ground in Europe?” use “Why Open Source Software Is Gaining Ground in Europe.”
- Instead of “Are You Losing Time and Money With Proprietary Software?” use “How Open Source Software Saves Time and Money.”
Writing for Easy Reading and Quick Scanning
Keep sentences to 25 words or less wherever possible, and keep paragraphs to 50 words or less if possible. Long sentences are difficult to parse and long paragraphs are off-putting for readers who are short on time or interest level. Vary sentence length within a paragraph to increase flow and readability.
- Modifiers: Avoid combining more than two modifiers. Consider rewording in cases where three or more descriptors are required.
- Bullets: Use bullets with parallel construction to highlight list items, especially for lists with three or more items. For more information, see Lists.
- Bolding: Bold text to draw attention to important words in the body, such as the first two or three words in a bulleted list. Do not use italics as it is often difficult to read. Do not underline text as people will assume it is a hyperlink.
- Contractions: Use contractions for a natural, more conversational approach to the content. Read sentences out loud to determine where contractions make the text sound less stilted.
- Conjunctions: Don’t be afraid to start sentences with And or But. This technique helps to create flow, and to keep sentences short, easy to read, and easy to understand.
- Consistency: Always use the same terminology when referring to Eclipse Foundation offerings and capabilities and to industry trends and best practices. While company insiders may use multiple terms to mean the same thing, it’s incredibly confusing for readers.
- Tense: In general, active text in the present tense is fastest and easiest for people to grasp. However, including passive sentences and the past tense are also needed for readability. Just be conscious of where and when these sentences are used.
Including Proof Points
When including proof points, always focus on facts and start with the basics:
- Always assume some readers are being introduced to the Eclipse Foundation or to the topic for the first time.
- Use adjectives and adverbs with discretion. While these words can be very helpful for describing benefits, using too many bloats content and distracts from key messages. Always choose factual adjectives that can be quantified or substantiated in the text that follows.
- Quantify all claims with facts and numbers.
- Do not make promises or guarantees of any kind.
- Focus on the strengths and benefits of the Eclipse Foundation and its approach rather than disparaging other organizations and approaches. If you need to contrast and compare approaches, be generic when possible, referring only to “other open source foundations” or “proprietary approaches.” If direct comparisons must be made, keep them purely factual.
When the content refers to Eclipse Foundation initiatives, projects, or working groups, always embed the link to the relevant webpage in the reference.
Avoid links that take readers off the Eclipse Foundation website. Links to GitHub pages for projects, YouTube channels, calendars, and other community-related pages are exceptions.
Avoid using “click here” as the linked text. Search engines and humans use the linked text to help identify what the link is about, so the linked text should indicate where the link will lead.
- The Eclipse Kura project is an IoT edge framework.
- EclipseCon 2020 was our first fully virtual EclipseCon.
- Eclipse Foundation working groups foster open industry collaboration.
- Check out the complete list of Jakarta EE TechTalks.
Referencing Source Material
When information from published sources other than Eclipse Foundation is included, the information must be:
- Identified with a footnote or endnote reference.
- Described with a title, author, and publication date or issue, if available, and a link in
the format shown below:
- Open Digital Platforms for the Industrial World in Europe 2020, PAC RADAR Report, July 2020: https://www.eurotech.com/en/page/open-digital-platforms-for-enterprise-iot-in-europe-2020.
Style and Punctuation
The Eclipse Foundation follows the Associated Press (AP) Stylebook guidelines for grammar and punctuation. This section briefly summarizes the guidelines for commonly used grammar and punctuation elements. For additional information, refer to the AP Stylebook.
Abbreviations and Acronyms
Spell out each abbreviation and acronym the first time it is used in the content body unless the term is extremely familiar to the audience.
Avoid using abbreviations and acronyms in headings unless expanding them would be too unwieldy or the acronyms are already widely used without expansion across industries and technologies. If the acronym is too unwieldy to spell out in a heading, expand it as early as possible in the content that follows.
Examples of familiar acronyms that do not need to be spelled out include:
- Protocols such as IP and HTTP
- LAN and WAN
- Technology names that include an acronym, such as a NoSQL database
Avoid overloading content with acronyms.
- If a term or phrase will not be used again in a document, you may not need to include the acronym.
- If a term or phrase is commonly used in its expanded form, prefer the expanded form.
- In quotes, provide the expanded form of the acronym if it hasn’t already been expanded in the content, but do not include the acronym in parentheses as this is not how people talk.
Don’t assume the audience is familiar with acronyms that are specific to the technology and processes at the Eclipse Foundation. If you’re not sure how a phrase is used, a quick internet search often helps. For example, searching on the phrase OSS technology returns references to operations support systems, not open source software.
To avoid confusion:
- Always spell out open source software.
- Be very judicious when using acronyms that “bury” the Eclipse brand, such as the Eclipse Cloud DevTools (ECD) Working Group or Eclipse Modeling Framework (EMF).
- When using the acronym IP in the context of intellectual property, always spell out the phrase first.
- When a project, working group, or event name includes an acronym, present the official
project name, but include an expansion of the acronym as close as possible to the name. For
- Eclipse Cyclone DDS implements the Data Distribution Service (DDS) specification.
- The Eclipse EMF Client Platform is a framework for building client applications that are based on the Eclipse Modeling Framework (EMF).
In longer content, and when less familiar acronyms are used, it will likely make sense to expand abbreviations and acronyms more than once to help readers recall what it means.
Be careful not to repeat words that are included in the acronym. For example, do not use:
- API interface
- PDF format
Capitalize the expanded term only if it is a proper name.
For a list of commonly used abbreviations and acronyms, see Commonly Used Acronyms and Abbreviations.
The examples below demonstrate correct use of apostrophes.
- When a software vendor’s implementation is based on…
- When software vendors’ implementations are based on…
- When software vendors implement specifications…
- Never use an apostrophe with a trademarked term.
- It’s is always a contraction for it is. Its refers back to a noun.
- It’s important to focus time and attention on the demonstration unit, its performance, and functionality.
When introducing a company, the general practice is to avoid using the legal entity in the business’ name in announcements, blog posts and press releases.
- Red Hat, not Red Hat, Inc.
Only when using a company name in a list or directory (e.g. Explore Our Members page) is the legal entity used.
In main headings and subheadings, capitalize each word, except the following prepositions when they occur in the middle of the heading:
- a, an, and, at, but, by, for, in, nor, of, on, or, so, the, to, up, yet
Capitalize a preposition in a title if it:
- Is used as an adjective or an adverb in a title.
- Has four or more letters, such as the word with.
- Is part of a project or working group name.
Always maintain the capitalization used in official project and working group names.
- Edge Robotics With Eclipse zenoh and ROS 2
- Following an Open Source Path to the Eclipse Foundation
- 2019 Was a Big Year for Eclipse Kuksa
- Eclipse ioFog 2.0 Is Just the Beginning
In the body of text, capitalize the names of people, places, and geographic regions.
Always use serial commas. Although the AP Stylebook indicates that a serial comma is not required to separate elements in a simple series, including the serial comma in all cases helps to avoid judgement errors.
Compound Words and Hyphenation
Use hyphens to join compound adjectives when they are used before a noun, but not in other cases.
- Jakarta EE 8-compatible products.
- Products compatible with Jakarta EE 8.
- Real-time access to information.
- Access to information in real time.
Follow these conventions for commonly used Eclipse Foundation terms:
- Never include a hyphen in open source as this phrase is treated as a collective noun:
- Open source software
- Open source software developers
- Open source initiative
- Cloud native should not be hyphenated as cloud-native
- Do include a hyphen when the phrase vendor neutral is used as a modifier:
- The Eclipse Foundation provides vendor-neutral governance.
- A vendor-neutral approach ensures …
- With governance that is vendor neutral, the Eclipse Foundation…
Do not use a hyphen after adverbs ending in ly or er.
- Highly flexible architecture
- Fully automated control
- Higher capacity solution
Use contractions for a natural, more conversational approach to the content. Read sentences out loud to determine where contractions make the text sound less stilted. Usually a combination of contractions and expansions sounds most natural.
Include numbers and symbols to specify amounts. When referring to currencies in general, use lower case.
- The industry experienced a $4 billion increase in….
- According to the report, €42 million will be needed to resolve…
- Millions of dollars were invested in the project.
- According to the report, millions of euros will be needed to resolve…
Dashes and Slashes
An en dash is equivalent to a hyphen. An en dash is used to indicate number ranges and to act as a kind of super-hyphen for compound modifiers.
The AP Stylebook does not deal with em dashes. These longer dashes are typically used to expand on information in a sentence. They should be used judiciously as they can make sentences overly long and complex. When used, include a space on each side of the em dash to adequately separate the information with the two dashes from the rest of the sentence.
Verify that the sentence is still clear if the information between the dashes is removed.
- Companies across industries — from hardware design to aerospace, insurance, and finance — are embracing open source software.
Do not use a slash between words. For clarity, use “and” or “or.”
Date and Time
When the date includes the day, month, date, and year:
- Spell out the day name.
- Abbreviate the month name if it is Jan., Feb., Aug., Sept., Oct., Nov. or Dec., and include a period after the abbreviation.
- Do not use ordinal number suffixes such as 1st, 2nd, 3rd, and 4th.
- Include a comma before the year.
- The announcement was made on Wednesday, Sept. 23, 2020.
- The announcement was made on Tuesday, March 10, 2020.
When the date includes just the month and the year, always spell out the month name and do not include the comma before the year.
- The announcement was in August 2020.
- The announcement was made in May 2020.
When the date includes just the month and date, abbreviate Jan., Feb., Aug., Sept., Oct., Nov. and Dec., and include a period after the abbreviation.
- The announcement was made on Oct. 19.
- The announcement was made on April 11.
If a date range is provided, use a hyphen with no space on each side to separate dates.
- July 21-22, 2020
- Nov. 23-27, 2020
Only use fully numeric dates when absolutely necessary due to space restrictions. In these rare cases, use the format MM/DD/YY.
- 9/21/20 for Sept. 21, 2020
Use the 12-hour clock and AM and PM to indicate time.
- 6:00 a.m.
- 7:30 p.m.
Email, Website, and Social Media References
Write email and website addresses in lowercase characters. Do not include www.
Embed the email address or URL into the text. If the address or URL is at the end of a sentence, ensure the period is not included in the address.
- To learn more, visit eclipse.org/membership.
- For more information, email firstname.lastname@example.org.
Whenever possible, embed website addresses into the text as a hyperlink.
- The technologies hosted at Eclipse IoT power the world’s leading commercial IoT solutions.
- With Eclipse Theia, developers can create cloud and desktop IDEs.
Link to the website for the project if one exists rather than the Eclipse Foundation project page:
Format general social media and web references as follows:
- To stay connected with the Eclipse Foundation, follow us on Twitter @EclipseFdn, LinkedIn, or visit eclipse.org.
Avoid using exclamation marks. They weaken the professional voice. They also make text sound overly eager and self-promotional.
In general, Eclipse Foundation content is written from a global perspective and specific locations are not identified. However, when locations do need to be identified:
- Capitalize geographic locations, even when they are regions.
- Western Hemisphere
- East Coast
- Middle East
- The Balkans
- Sub-Saharan Africa
- Use the following country abbreviations, even on first reference:
- U.S. for United States. Do not use USA or United States of America unless it is required in the context of the content.
- UK for United Kingdom.
- Always spell out continent names in full.
Language and Spelling
Write all content in American English following the spelling in the Merriam-Webster Dictionary. When two spellings are provided, use the first entry.
However, keep in mind the audience for Eclipse Foundation content is typically global, so do not include words, terms, or phrases that would be unfamiliar to people who don’t have English as a first language.
When choosing words and phrases, always choose those that are the most accurate and meaningful for the target audience. While we can assume some level of technical understanding in all audiences, that level will vary depending on the content type. For example, the language used in an in-depth technical article will differ from the language used in a press release or annual report.
Do not include Latinisms such as e.g., i.e., etc. as they may not be understood by all readers, especially those who do not have a strong background in English.
- For example, instead of e.g.
- That is, instead of i.e.
- And more, instead of etc.
A list is needed when there are more than three items and when each list item is long enough that it is difficult to read in a sentence — usually four or five words.
Use bullets to identify list items unless a specific order of operations is required. In simple running lists, put list items in alphabetical order.
Always introduce lists with a sentence or short phrase that ends with a colon.
Start each list item with a capital letter on a separate line.
Use parallel construction for each item in the list:
- Use only complete sentences or incomplete sentences.
- Start every list item with the same part of speech, such as a verb or a noun.
- Use the same voice (active or passive) and verb tense.
Put the most important words for the reader to grasp at the beginning of the list item.
Include a period at the end of the list items that are complete sentences. Do not use any punctuation at the end of list items that are incomplete sentences.
Keep lists to seven items or less if possible. If it is not possible, consider categorizing list items or using sub-bullets.
Avoid creating lists of questions. Rephrase the list introduction and items so they form statements.
Names and Job Titles
When it is necessary to refer to specific individuals, capitalize their job title when it is used before their name in a formal way, but use lowercase when it is included after their name and when referring to the role in general.
- Company President and CEO, Joe Smith, said he was…
- Joe Smith, the president and CEO of the company, said he was…
- As president and CEO of the company, Joe Smith said he was…
Numbers, Statistics, and Prices
Write out the numbers zero to nine. Use numerals for numbers 10 and higher. Do not include suffixes such as st, nd, rd, or th on numbers.
Use a comma to separate numbers that have four or more digits.
Use dots in telephone numbers, even for the area code. Always include the country code with a + symbol.
When making general references to numbers in marketing content, it often makes sense to round them up or simply indicate order of magnitude if the number is likely to change. Always provide the specific number when referring to technical advances.
- The Eclipse Foundation hosts more than 375 open source software projects.
- The results were 99.9 percent accurate.
- The software is 12 times faster than previous versions.
- Our membership increased by 25 percent.
Periods, Colons, and Semicolons
Use a period to end a complete sentence, but not an incomplete sentence such as a list item.
Always use a colon to introduce a list.
In running text, capitalize the first word after the colon only if it is a proper noun or the start of a complete sentence.
- Eclipse Foundation: The home of entrepreneurial open source software.
- Eclipse Foundation members enjoy key benefits: intellectual property services, marketing and IT services, and mentorship.
Avoid writing sentences that include a semicolon. Use two sentences instead. If you must use a semicolon, use it as a greater separation of thought than a comma, but less than a period.
- Complete sentences should be punctuated; incomplete sentences should not.
In general, use quotation marks only when quoting someone.
Put all punctuation inside quotation marks, making it clear who is being quoted.
- “The open source software at the Eclipse Foundation has been important to our business success,” says Mary Smith. “We plan to get involved in more projects and encourage our developers to become committers.”
Quotation marks should only be used when quoting a complete thought, and are not necessary when repeating a few select words from a larger quotation.
- Avoid: Smith said he “saw an opportunity” to contribute from a technology perspective.
- Instead: Smith said he saw an opportunity to contribute from a technology perspective.
Avoid using quotation marks to call attention to words that are likely to be unfamiliar to readers or to highlight a less formal term or phrase. Instead, put unfamiliar and less formal words in context to explain their meaning, or use bold to emphasize them.
In some cases, it may be necessary to use quotation marks to separate a particular word or phrase from the surrounding text, but always take a moment to confirm there is no better way to communicate the thought.
Always write out the word percent.
Use ampersands only when they are part of an official name. Otherwise, always use “and.”
Avoid putting information in parentheses unless you are expanding an acronym or abbreviation. In general, information in parentheses in running text tells the reader they can ignore the information. Reword the sentence or find another way to communicate the information in parentheses.
Tables are usually used to show a data set or compare categories of information. They are often a very clear way to summarize and present complex information.
When creating a table:
- Organize the structure so that all, or almost all, cells will have information in them
- Don’t leave cells blank. Include the words “Not applicable.”
- Indicate units of measure in the column heading rather than each cell if every cell uses the same units.
- Follow the capitalization guidelines in column headings.
If notes are needed to qualify information in table cells, manually create a superscript footnote reference within the cell and provide the explanation directly below the table using the same superscript number.
When referring to technical standards, include the standard title or a description of what the standard covers along with the standard number the first time it is referenced. When referring to multiple standards, using a bulleted list to convey this information is usually the best approach.
Double-check capitalization, hyphenation, spacing, and letter revision in the names of standards on the standards webpage as these aspects of the official standard name are often dropped in casual references.