diff options
| author | Eric Poirier | 2021-03-19 14:32:26 +0000 |
|---|---|---|
| committer | Eric Poirier | 2021-03-22 12:19:53 +0000 |
| commit | 4974afaf9ed8b0fde09fe127e06bb680df092310 (patch) | |
| tree | a7cef396e672c537802359a548fa9863ed190aa1 | |
| parent | 787821756f465c024ceb4269a123b9c8522d5e36 (diff) | |
| download | org-4974afaf9ed8b0fde09fe127e06bb680df092310.tar.gz org-4974afaf9ed8b0fde09fe127e06bb680df092310.tar.xz org-4974afaf9ed8b0fde09fe127e06bb680df092310.zip | |
Bug 572046 - Create new Writting Style Guide page
Change-Id: If4d78da77cc2bf7055a648edded6f2f0f8520f4c
Signed-off-by: Eric Poirier <eric.poirier@eclipse-foundation.org>
| -rw-r--r-- | documents/writting-style-guide/content/en_index.php | 913 | ||||
| -rw-r--r-- | documents/writting-style-guide/index.php | 34 |
2 files changed, 947 insertions, 0 deletions
diff --git a/documents/writting-style-guide/content/en_index.php b/documents/writting-style-guide/content/en_index.php new file mode 100644 index 00000000..8f1b47d2 --- /dev/null +++ b/documents/writting-style-guide/content/en_index.php @@ -0,0 +1,913 @@ +<?php +/** + * Copyright (c) 2005, 2018, 2021 Eclipse Foundation and others. + * + * This program and the accompanying materials are made + * available under the terms of the Eclipse Public License 2.0 + * which is available at https://www.eclipse.org/legal/epl-2.0/ + * + * Contributors: + * Eric Poirier (Eclipse Foundation) - initial API and implementation + */ +?> +<div id="maincontent"> + <div id="midcolumn"> + <h1><?php print $pageTitle; ?></h1> + <ul> + <li><a href="#1">Using This Guide</a></li> + <li><a href="#2">Representing the Brand</a> + <ul> + <li><a href="#41">Trademarks and Copyright</a> + <li><a href="#3">Tone and Voice</a></li> + <li><a href="#4">Using Our Name</a></li> + <li><a href="#5">Referring to Projects and Working Groups</a></li> + <li><a href="#6">Referring to Communities</a></li> + <li><a href="#7">Referring to People</a></li> + </ul></li> + <li><a href="#8">Telling the Story</a> + <ul> + <li><a href="#9">Organizing Content to Capture Attention</a></li> + <li><a href="#10">Incorporating SEO Keywords</a></li> + <li><a href="#11">Writing Effective Headings</a></li> + <li><a href="#12">Writing for Easy Reading and Quick Scanning</a></li> + <li><a href="#13">Including Proof Points</a></li> + <li><a href="#14">Incorporating Links</a></li> + <li><a href="#15">Referencing Source Material</a></li> + </ul></li> + <li><a href="#16">Style and Punctuation</a> + <ul> + <li><a href="#17">Abbreviations and Acronyms</a></li> + <li><a href="#18">Apostrophes</a></li> + <li><a href="#40">Business Entities</a> + <li><a href="#19">Capitalization</a></li> + <li><a href="#20">Commas</a></li> + <li><a href="#21">Compound Words and Hyphenation</a></li> + <li><a href="#22">Contractions</a></li> + <li><a href="#23">Currencies</a></li> + <li><a href="#24">Dashes and Slashes</a></li> + <li><a href="#25">Date and Time</a></li> + <li><a href="#26">Email, Website, and Social Media References</a></li> + <li><a href="#28">Exclamation Marks</a></li> + <li><a href="#29">Geographic Names</a></li> + <li><a href="#30">Language and Spelling</a></li> + <li><a href="#31">Latinisms</a></li> + <li><a href="#32">Lists</a></li> + <li><a href="#33">Names and Job Titles</a></li> + <li><a href="#34">Numbers, Statistics, and Prices</a></li> + <li><a href="#35">Periods, Colons, and Semicolons</a></li> + <li><a href="#36">Quotation Marks</a></li> + <li><a href="#37">Symbols</a></li> + <li><a href="#38">Tables</a></li> + <li><a href="#39">Technical Standards</a></li> + </ul></li> + </ul> + <h1 id="1">Using This Guide</h1> + <p>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:</p> + <ul> + <li>Editorial guidelines for each content type</li> + <li>AP Stylebook</li> + </ul> + <h2>Audience</h2> + <p>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:</p> + <ul> + <li>Employees of the Eclipse Foundation</li> + <li>Media members and third-party content developers</li> + <li>Agencies producing content on behalf of the Eclipse Foundation</li> + </ul> + + <h1 id="2">Representing the Brand</h1> + <p> + Write all content in American English following the spelling in the<a + href="https://www.merriam-webster.com/" + > Merriam-Webster Dictionary</a>. When two spellings are provided, use the first entry. + </p> + <p>General guidelines:</p> + <ul> + <li>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.</li> + <li>Never include colloquialisms or culturally specific references.</li> + <li>Use universally understood terms. Avoid clichés, jargon, outdated expressions, and + phrases that only industry insiders will understand.</li> + <li>Avoid overused phrases and marketing hype.</li> + </ul> + <h2 id="41">Trademarks and Copyright</h2> + <p> + Please visit the <a href="https://www.eclipse.org/legal/logo_guidelines.php">Eclipse logo and + Trademark Guidelines</a> section of the Eclipse Foundation website for further details on + trademark usage. + </p> + <p>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.</p> + <p>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.</p> + <p>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." </p> + <p>Use the format: © 2020 Eclipse Foundation. All rights reserved.</p> + <p>The copyright year is always the year the content was first published, even if the + content is updated in a subsequent year.</p> + <p>Example:</p> + <ul> + <li>© 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.</li> + </ul> + <h2 id="3">Tone and Voice</h2> + <p>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.</p> + <p>The tone should be direct, informative, and helpful, but never condescending, patronizing, or + overly casual:</p> + <ul> + <li>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.</li> + <li>Use third-person writing style to identify the audience in the content and for more formal + content, such as white papers.</li> + <li>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.</li> + </ul> + <h2 id="4">Using Our Name</h2> + <p>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.</p> + <p>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.</p> + <p>In addition:</p> + <ul> + <li>Avoid using the Eclipse Foundation name in a possessive construction such as “The + Eclipse Foundation’s … ”</li> + <li>After first use, Eclipse Foundation can be replaced with we, us, or our.</li> + <li>Only capitalize “the” in the Eclipse Foundation if it is at the beginning of a + sentence.</li> + </ul> + <h2>Referring to Membership Levels</h2> + <p>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. </p> + <ul> + <li>Eclipse Foundation membership provides certain benefits...</li> + <li>Eclipse Foundation members gain access to…</li> + <li>A Strategic Member of the Eclipse Foundation has access to...</li> + </ul> + <h2 id="5">Referring to Projects and Working Groups</h2> + <p>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.</p> + <p>To avoid the impression of ownership or control, refrain from using the following phrases:</p> + <ul> + <li>Eclipse Foundation projects</li> + <li>Eclipse Foundation research projects</li> + <li>Eclipse Foundation working groups</li> + </ul> + <p>Instead use variations that more clearly indicate the relationships:</p> + <ul> + <li>Projects hosted at the Eclipse Foundation…</li> + <li>Community projects at the Eclipse Foundation…</li> + <li>The Eclipse Foundation is home to several working groups…</li> + <li>Working groups at the Eclipse Foundation…</li> + </ul> + <p>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.</p> + <p>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. </p> + <p> + The <a href="https://projects.eclipse.org/">project page</a> displays the formal name, along + with other potentially useful information about the project. + </p> + <p>There are some exceptions. </p> + <p>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”.</p> + <p>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.</p> + <p>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.”</p> + <p>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”. </p> + <p>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”).</p> + <p>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. </p> + <p>Capitalize the names of projects, unless the name is purposely lowercase.</p> + <ul> + <li>Eclipse Theia project</li> + <li>Eclipse zenoh project</li> + </ul> + <p>Capitalize the phrase “working group” when it is included in the working group + name, but not when the concept is referred to in general. </p> + <p>Examples:</p> + <ul> + <li>Eclipse IoT Working Group</li> + <li>Jakarta EE Working Group</li> + <li>openGENESIS Working Group</li> + <li>The working groups hosted at the Eclipse Foundation…</li> + </ul> + <h2 id="6">Referring to Communities</h2> + <p>Use the word community to refer to the different groups that are associated with the Eclipse + Foundation:</p> + <ul> + <li>The Eclipse Foundation is a community.</li> + <li>Each project and working group hosted at the Eclipse Foundation is also a community.</li> + <li>Each Eclipse Foundation community provides benefits to the ecosystem related to that + technology area.</li> + </ul> + <p>Examples:</p> + <ul> + <li>We invite the entire Eclipse Foundation community to…</li> + <li>The Eclipse Hono community will be hosting…</li> + <li>The Jakarta EE community delivers benefits to the Java ecosystem…</li> + <li>The Eclipse Edge Native Working Group focuses on edge technologies for the IoT + ecosystem…</li> + </ul> + <h2 id="7">Referring to People</h2> + <p>Remember that there are different ways to refer to people associated with the Eclipse + Foundation and projects hosted by the foundation.</p> + <p>The organizations and individuals who use the technologies are users.</p> + <p>The organizations and individuals who incorporate technologies in their own products and + projects are adopters.</p> + <p>The developers who actively work on projects are contributors or committers.</p> + <p>The people who are involved in working groups are members of the working group.</p> + <p>Organizations that pay an annual fee to participate in the Eclipse Foundation are members of + the Eclipse Foundation.</p> + <p>Two general terms are also used to refer to people:</p> + <ul> + <li>Consumers are the people who use open source software, the adopters.</li> + <li>Producers are the developers who create and enhance open source software.</li> + </ul> + <h1 id="8">Telling the Story</h1> + <p>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:</p> + <ul> + <li>Software developers</li> + <li>Software architects and decision-makers</li> + <li>Product owners</li> + <li>Chief Technology Officers and other C-level executives</li> + <li>Academics and researchers</li> + <li>Eclipse Foundation members</li> + <li>Staff at industry publications</li> + <li>Industry analysts</li> + <li>Media</li> + </ul> + <p>Always tell the story from the audience perspective, not the Eclipse Foundation perspective:</p> + <ul> + <li>Instead of thinking, “what are all of the things I want to tell the audience?” + think, “what is it the audience needs to know?”</li> + <li>Present the information in the context of how the Eclipse Foundation helps the audience + achieve its goals.</li> + </ul> + <h2 id="9">Organizing Content to Capture Attention</h2> + <p>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.</p> + <p>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.</p> + <p>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.</p> + <p>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.</p> + <p>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.</p> + <h2 id="10">Incorporating SEO Keywords</h2> + <p>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.</p> + <p>Always include keywords in the following elements when you write Eclipse Foundation content:</p> + <ul> + <li>Main headings and webpage titles</li> + <li>Subheads</li> + <li>URLs</li> + <li>Opening statements</li> + </ul> + <p> + 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<a href="https://backlinko.com/hub/seo/lsi"> latent semantic indexing</a>. + </p> + <p>Depending on the project, you may also be asked to provide:</p> + <ul> + <li>Alt text for images</li> + <li>Title tags</li> + <li>Meta descriptions</li> + </ul> + <p>Each of these text elements should also include keywords. </p> + <p>The marketing manager will work with the web team to ensure Eclipse Foundation URLs are short + and include at least one keyword.</p> + <p> + 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<a + href="https://backlinko.com/on-page-seo" + > this guide</a>. + </p> + <h2 id="11">Writing Effective Headings</h2> + <p>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.</p> + <p>Examples:</p> + <ul> + <li>Open Source Collaboration Drives Faster, Lower-Cost Innovation to Increase Competitiveness</li> + <li>Eclipse Foundation Open Source Communities Give European Organizations Crucial Advantages</li> + <li>The Eclipse Sparkplug Protocol Augments MQTT With IIoT Interoperability Essentials</li> + <li>Jakarta EE Adoption and Compatible Implementations Are on the Rise</li> + </ul> + <p>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.</p> + <p>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:</p> + <ul> + <li>No.</li> + <li>Yes.</li> + <li>I don’t care.</li> + <li>That question doesn’t apply to me.</li> + </ul> + <p>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.</p> + <p>Examples:</p> + <ul> + <li>Instead of “Why Is Open Source Software Gaining Ground in Europe?” use + “Why Open Source Software Is Gaining Ground in Europe.”</li> + <li>Instead of “Are You Losing Time and Money With Proprietary Software?” use + “How Open Source Software Saves Time and Money.”</li> + </ul> + <h2 id="12">Writing for Easy Reading and Quick Scanning</h2> + <p>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.</p> + <ul> + <li><strong>Modifiers</strong>: Avoid combining more than two modifiers. Consider rewording in + cases where three or more descriptors are required.</li> + <li><strong>Bullets</strong>: Use bullets with parallel construction to highlight list items, + especially for lists with three or more items. For more information, see <a + href="#h.6ohc93azle1z" + >Lists</a>.</li> + <li><strong>Bolding</strong>: 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.</li> + <li><strong>Contractions</strong>: 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.</li> + <li><strong>Conjunctions</strong>: 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.</li> + <li><strong>Consistency</strong>: 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.</li> + <li><strong>Tense</strong>: 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.</li> + </ul> + <h2 id="13">Including Proof Points</h2> + <p>When including proof points, always focus on facts and start with the basics:</p> + <ul> + <li>Always assume some readers are being introduced to the Eclipse Foundation or to the topic + for the first time.</li> + <li>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.</li> + <li>Quantify all claims with facts and numbers.</li> + <li>Do not make promises or guarantees of any kind.</li> + <li>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.</li> + </ul> + <h2 id="14">Incorporating Links</h2> + <p>When the content refers to Eclipse Foundation initiatives, projects, or working groups, + always embed the link to the relevant webpage in the reference. </p> + <p>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.</p> + <p> + When a project website is available (e.g. <a href="https://www.eclipse.org/kura/">eclipse.org/kura</a>), + the best practice is to link to it instead of the project page (e.g. <a + href="https://projects.eclipse.org/projects/iot.kura" + >projects.eclipse.org/projects/iot.kura</a>). + </p> + <p>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. </p> + <p>Examples:</p> + <ul> + <li>The<a href="https://www.eclipse.org/kura/"> Eclipse Kura</a> project is an IoT edge + framework. + </li> + <li><a href="https://www.eclipsecon.org/2020">EclipseCon 2020</a> was our first fully virtual + EclipseCon.</li> + <li><a href="https://www.eclipse.org/org/workinggroups/">Eclipse Foundation working groups</a> + foster open industry collaboration.</li> + <li>Check out the complete list of <a + href="https://www.youtube.com/playlist?list=PLy7t4z5SYNaSvv9SjVVi6-8SVdwpk-rxM" + >Jakarta EE TechTalks</a>. + </li> + </ul> + <h2 id="15">Referencing Source Material</h2> + <p>When information from published sources other than Eclipse Foundation is included, the + information must be:</p> + <ul> + <li>Identified with a footnote or endnote reference.</li> + <li>Described with a title, author, and publication date or issue, if available, and a link in + the format shown below: + <ul> + <li>Open Digital Platforms for the Industrial World in Europe 2020, PAC RADAR Report, July + 2020:<a + href="https://www.eurotech.com/en/page/open-digital-platforms-for-enterprise-iot-in-europe-2020" + > + https://www.eurotech.com/en/page/open-digital-platforms-for-enterprise-iot-in-europe-2020</a>. + </li> + </ul> + </li> + </ul> + <h1 id="16">Style and Punctuation</h1> + <p>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.</p> + <h2 id="17">Abbreviations and Acronyms</h2> + <p>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.</p> + <p>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.</p> + <p>Examples of familiar acronyms that do not need to be spelled out include:</p> + <ul> + <li>API</li> + <li>IDE</li> + <li>IoT</li> + <li>Protocols such as IP and HTTP</li> + <li>LAN and WAN</li> + <li>Technology names that include an acronym, such as a NoSQL database</li> + </ul> + <p>Avoid overloading content with acronyms.</p> + <ul> + <li>If a term or phrase will not be used again in a document, you may not need to include the + acronym.</li> + <li>If a term or phrase is commonly used in its expanded form, prefer the expanded form.</li> + <li>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. </li> + </ul> + <p>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.</p> + <p>To avoid confusion:</p> + <ul> + <li>Always spell out open source software.</li> + <li>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). </li> + <li>When using the acronym IP in the context of intellectual property, always spell out the + phrase first.</li> + <li>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 + example: + <ul> + <li>Eclipse Cyclone DDS implements the Data Distribution Service (DDS) specification.</li> + <li>The Eclipse EMF Client Platform is a framework for building client applications that + are based on the Eclipse Modeling Framework (EMF). </li> + </ul> + </li> + </ul> + <p>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. </p> + <p>Be careful not to repeat words that are included in the acronym. For example, do not use:</p> + <ul> + <li>API interface</li> + <li>PDF format</li> + </ul> + <p>Capitalize the expanded term only if it is a proper name.</p> + <p>For a list of commonly used abbreviations and acronyms, see Commonly Used Acronyms and + Abbreviations.</p> + <h2 id="18">Apostrophes</h2> + <p>The examples below demonstrate correct use of apostrophes.</p> + <ul> + <li>When a software vendor’s implementation is based on…</li> + <li>When software vendors’ implementations are based on…</li> + <li>When software vendors implement specifications… </li> + </ul> + <p>Remember:</p> + <ul> + <li>Never use an apostrophe with a trademarked term.</li> + <li>It’s is always a contraction for it is. Its refers back to a noun. + <ul> + <li>It’s important to focus time and attention on the demonstration unit, its + performance, and functionality.</li> + </ul> + </li> + </ul> + <h2 id="40">Business Entities</h2> + <p>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. </p> + <p>Example:</p> + <ul> + <li>Red Hat, not Red Hat, Inc.</li> + </ul> + <p> + Only when using a company name in a list or directory (e.g. <a + href="https://www.eclipse.org/membership/exploreMembership.php" + >Explore Our Members page</a>) is the legal entity used. + </p> + <h2 id="19">Capitalization</h2> + <p>In main headings and subheadings, capitalize each word, except the following prepositions + when they occur in the middle of the heading:</p> + <ul> + <li>a, an, and, at, but, by, for, in, nor, of, on, or, so, the, to, up, yet</li> + </ul> + <p>Capitalize a preposition in a title if it:</p> + <ul> + <li>Is used as an adjective or an adverb in a title.</li> + <li>Has four or more letters, such as the word with.</li> + <li>Is part of a project or working group name.</li> + </ul> + <p>Always maintain the capitalization used in official project and working group names. </p> + <p>Examples:</p> + <ul> + <li>Edge Robotics With Eclipse zenoh and ROS 2</li> + <li>Following an Open Source Path to the Eclipse Foundation</li> + <li>2019 Was a Big Year for Eclipse Kuksa</li> + <li>Eclipse ioFog 2.0 Is Just the Beginning</li> + </ul> + <p>In the body of text, capitalize the names of people, places, and geographic regions.</p> + <h2 id="20">Commas</h2> + <p>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.</p> + <h2 id="21">Compound Words and Hyphenation</h2> + <p>Use hyphens to join compound adjectives when they are used before a noun, but not in other + cases.</p> + <p>Examples:</p> + <ul> + <li>Jakarta EE 8-compatible products.</li> + <li>Products compatible with Jakarta EE 8.</li> + <li>Real-time access to information.</li> + <li>Access to information in real time.</li> + </ul> + <p>Follow these conventions for commonly used Eclipse Foundation terms:</p> + <ul> + <li>Never include a hyphen in open source as this phrase is treated as a collective noun: + <ul> + <li>Open source software</li> + <li>Open source software developers</li> + <li>Open source initiative</li> + </ul> + </li> + <li>Cloud native should not be hyphenated as cloud-native</li> + <li>Do include a hyphen when the phrase vendor neutral is used as a modifier: + <ul> + <li>The Eclipse Foundation provides vendor-neutral governance.</li> + <li>A vendor-neutral approach ensures …</li> + <li>With governance that is vendor neutral, the Eclipse Foundation…</li> + </ul> + </li> + </ul> + <p>Do not use a hyphen after adverbs ending in ly or er.</p> + <p>Examples:</p> + <ul> + <li>Highly flexible architecture</li> + <li>Fully automated control</li> + <li>Higher capacity solution</li> + </ul> + <h2 id="22">Contractions</h2> + <p>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.</p> + <h2 id="23">Currencies</h2> + <p>Include numbers and symbols to specify amounts. When referring to currencies in general, use + lower case.</p> + <p>Examples:</p> + <ul> + <li>The industry experienced a $4 billion increase in….</li> + <li>According to the report, €42 million will be needed to resolve…</li> + <li>Millions of dollars were invested in the project.</li> + <li>According to the report, millions of euros will be needed to resolve…</li> + </ul> + <h2 id="24">Dashes and Slashes</h2> + <p>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. </p> + <p>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.</p> + <p>Verify that the sentence is still clear if the information between the dashes is removed.</p> + <p>Example:</p> + <ul> + <li>Companies across industries — from hardware design to aerospace, insurance, and + finance — are embracing open source software.</li> + </ul> + <p>Do not use a slash between words. For clarity, use “and” or “or.”</p> + <h2 id="25">Date and Time</h2> + <p>When the date includes the day, month, date, and year:</p> + <ul> + <li>Spell out the day name.</li> + <li>Abbreviate the month name if it is Jan., Feb., Aug., Sept., Oct., Nov. or Dec., and + include a period after the abbreviation.</li> + <li>Do not use ordinal number suffixes such as 1st, 2nd, 3rd, and 4th.</li> + <li>Include a comma before the year.</li> + </ul> + <p>Examples:</p> + <ul> + <li>The announcement was made on Wednesday, Sept. 23, 2020.</li> + <li>The announcement was made on Tuesday, March 10, 2020.</li> + </ul> + <p>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.</p> + <p>Examples:</p> + <ul> + <li>The announcement was in August 2020.</li> + <li>The announcement was made in May 2020.</li> + </ul> + <p>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. </p> + <p>Examples:</p> + <ul> + <li>The announcement was made on Oct. 19.</li> + <li>The announcement was made on April 11.</li> + </ul> + <p>If a date range is provided, use a hyphen with no space on each side to separate dates.</p> + <p>Examples:</p> + <ul> + <li>July 21-22, 2020</li> + <li>Nov. 23-27, 2020</li> + </ul> + <p>Only use fully numeric dates when absolutely necessary due to space restrictions. In these + rare cases, use the format MM/DD/YY.</p> + <p>Example:</p> + <ul> + <li>9/21/20 for Sept. 21, 2020</li> + </ul> + <p>Use the 12-hour clock and AM and PM to indicate time.</p> + <p>Examples:</p> + <ul> + <li>6:00 a.m.</li> + <li>7:30 p.m.</li> + </ul> + <h2 id="26">Email, Website, and Social Media References</h2> + <p>Write email and website addresses in lowercase characters. Do not include www.</p> + <p>Examples:</p> + <ul> + <li><a href="mailto:membership@eclipse.org">membership@eclipse.org</a></li> + <li><a href="https://www.eclipse.org/membership/">eclipse.org/membership</a></li> + <li><a href="https://www.eclipse.org/">eclipse.org</a></li> + </ul> + <p>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. </p> + <p>Examples:</p> + <ul> + <li>To learn more, visit<a href="https://www.eclipse.org/membership/"> eclipse.org/membership</a>. + </li> + <li>For more information, email membership@eclipse.org. </li> + </ul> + <p>Whenever possible, embed website addresses into the text as a hyperlink.</p> + <p>Examples:</p> + <ul> + <li>The technologies hosted at<a href="https://iot.eclipse.org/"> Eclipse IoT</a> power the + world’s leading commercial IoT solutions. + </li> + <li>With<a href="https://theia-ide.org/"> Eclipse Theia</a>, developers can create cloud and + desktop IDEs. + </li> + </ul> + <p>Link to the website for the project if one exists rather than the Eclipse Foundation project + page:</p> + <ul> + <li><a href="https://theia-ide.org/">Eclipse Theia</a> rather than<a + href="https://projects.eclipse.org/projects/ecd.theia" + > Eclipse Theia</a>.</li> + </ul> + <p>Format general social media and web references as follows:</p> + <ul> + <li>To stay connected with the Eclipse Foundation, follow us on Twitter @EclipseFdn, LinkedIn, + or visit<a href="https://www.eclipse.org/"> eclipse.org</a>. + </li> + </ul> + <h2 id="28">Exclamation Marks</h2> + <p>Avoid using exclamation marks. They weaken the professional voice. They also make text sound + overly eager and self-promotional.</p> + <h2 id="29">Geographic Names</h2> + <p>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:</p> + <ul> + <li>Capitalize geographic locations, even when they are regions.</li> + <li>Examples: + <ul> + <li>Western Hemisphere</li> + <li>East Coast</li> + <li>Middle East</li> + <li>The Balkans</li> + <li>Sub-Saharan Africa</li> + </ul> + </li> + <li>Use the following country abbreviations, even on first reference: + <ul> + <li>U.S. for United States. Do not use USA or United States of America unless it is + required in the context of the content.</li> + <li>UK for United Kingdom.</li> + </ul> + </li> + <li>Always spell out continent names in full.</li> + </ul> + <h2 id="30">Language and Spelling</h2> + <p> + Write all content in American English following the spelling in the<a + href="https://www.merriam-webster.com/" + > Merriam-Webster Dictionary</a>. When two spellings are provided, use the first entry. + </p> + <p>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.</p> + <p>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.</p> + <h2 id="31">Latinisms</h2> + <p>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. </p> + <p>Use:</p> + <ul> + <li>For example, instead of e.g.</li> + <li>That is, instead of i.e.</li> + <li>And more, instead of etc.</li> + </ul> + <h2 id="32">Lists</h2> + <p>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.</p> + <p>Use bullets to identify list items unless a specific order of operations is required. In + simple running lists, put list items in alphabetical order.</p> + <p>Always introduce lists with a sentence or short phrase that ends with a colon.</p> + <p>Start each list item with a capital letter on a separate line.</p> + <p>Use parallel construction for each item in the list:</p> + <ul> + <li>Use only complete sentences or incomplete sentences.</li> + <li>Start every list item with the same part of speech, such as a verb or a + noun.</li> + <li>Use the same voice (active or passive) and verb tense. </li> + </ul> + <p>Put the most important words for the reader to grasp at the beginning of the list item.</p> + <p>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. </p> + <p>Keep lists to seven items or less if possible. If it is not possible, consider categorizing + list items or using sub-bullets.</p> + <p>Avoid creating lists of questions. Rephrase the list introduction and items so they form + statements.</p> + <h2 id="33">Names and Job Titles</h2> + <p>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.</p> + <p>Examples:</p> + <ul> + <li>Company President and CEO, Joe Smith, said he was…</li> + <li>Joe Smith, the president and CEO of the company, said he was…</li> + <li>As president and CEO of the company, Joe Smith said he was…</li> + </ul> + <h2 id="34">Numbers, Statistics, and Prices</h2> + <p>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.</p> + <p>Use a comma to separate numbers that have four or more digits.</p> + <p>Use dots in telephone numbers, even for the area code. Always include the country code with a + + symbol.</p> + <p>Example: +1.123.555.6789</p> + <p>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.</p> + <p>Examples:</p> + <ul> + <li>The Eclipse Foundation hosts more than 375 open source software projects.</li> + <li>The results were 99.9 percent accurate.</li> + <li>The software is 12 times faster than previous versions.</li> + <li>Our membership increased by 25 percent.</li> + </ul> + <h2 id="35">Periods, Colons, and Semicolons</h2> + <p>Use a period to end a complete sentence, but not an incomplete sentence such as a list item.</p> + <p>Always use a colon to introduce a list.</p> + <p>In running text, capitalize the first word after the colon only if it is a proper noun or the + start of a complete sentence.</p> + <p>Examples:</p> + <ul> + <li>Eclipse Foundation: The home of entrepreneurial open source software.</li> + <li>Eclipse Foundation members enjoy key benefits: intellectual property services, marketing + and IT services, and mentorship. </li> + </ul> + <p>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.</p> + <p>Example:</p> + <ul> + <li>Complete sentences should be punctuated; incomplete sentences should not.</li> + </ul> + <h2 id="36">Quotation Marks</h2> + <p>In general, use quotation marks only when quoting someone.</p> + <p>Put all punctuation inside quotation marks, making it clear who is being quoted.</p> + <p>Example:</p> + <ul> + <li>“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.”</li> + </ul> + <p>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. </p> + <p>Example: </p> + <ul> + <li><strong>Avoid</strong>: Smith said he “saw an opportunity” to contribute from + a technology perspective.</li> + <li><strong>Instead</strong>: Smith said he saw an opportunity to contribute from a technology + perspective.</li> + </ul> + <p>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. </p> + <p>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.</p> + <h2 id="37">Symbols</h2> + <p>Always write out the word percent.</p> + <p>Use ampersands only when they are part of an official name. Otherwise, always use + “and.”</p> + <p>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.</p> + <h2 id="38">Tables</h2> + <p>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.</p> + <p>When creating a table:</p> + <ul> + <li>Organize the structure so that all, or almost all, cells will have information in them</li> + <li>Don’t leave cells blank. Include the words “Not applicable.”</li> + <li>Indicate units of measure in the column heading rather than each cell if every cell uses + the same units.</li> + <li>Follow the <a + href="#h.dds8zk4m0vi2" + >capitalization guidelines</a> in column headings. + </li> + </ul> + <p>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.</p> + <h2 id="39">Technical Standards</h2> + <p>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.</p> + <p>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.</p> + </div> + <div id="rightcolumn"> + <div class="sideitem"> + <h6>Related Links</h6> + <ul> + <li><a href="../membership/">Membership</a></li> + <li><a href="../membership/become_a_member/">Become a member</a></li> + </ul> + </div> + <div class="sideitem"> + <h6>Thank you!</h6> + <p> + Thanks to our many <a href="/corporate_sponsors/">Corporate Sponsors</a> + for their generous donations to our infrastructure. + </p> + </div> + </div> +</div>
\ No newline at end of file diff --git a/documents/writting-style-guide/index.php b/documents/writting-style-guide/index.php new file mode 100644 index 00000000..c118015e --- /dev/null +++ b/documents/writting-style-guide/index.php @@ -0,0 +1,34 @@ +<?php +/** + * Copyright (c) 2021 Eclipse Foundation. + * + * This program and the accompanying materials are made + * available under the terms of the Eclipse Public License 2.0 + * which is available at https://www.eclipse.org/legal/epl-2.0/ + * + * Contributors: + * Eric Poirier (Eclipse Foundation) + */ + +require_once ($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/app.class.php"); +require_once ($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/nav.class.php"); + +$App = new App(); +$Nav = new Nav(); +$Theme = $App->getThemeClass(); + +include ($App->getProjectCommon()); + +$pageTitle = "Eclipse Foundation Writing Style Guide"; +$Theme->setPageTitle($pageTitle); +$Theme->setPageKeywords("writing style guide, documents, Eclipse Foundation"); +$Theme->setPageAuthor("Eclipse Foundation"); + +ob_start(); +include("content/en_" . $App->getScriptName()); +$html = ob_get_clean(); + +$Theme->setNav($Nav); +$Theme->setHtml($html); +$Theme->generatePage(); + |