You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
200 lines
11 KiB
200 lines
11 KiB
<h1 id="language"></h1>
|
|
<div class="page-header mb-0 mt-5 pl-4 pt-2 pb-0">
|
|
<h2>Language & grammar</h2>
|
|
</div>
|
|
<div class="row">
|
|
<div class="col-12 pl-4 pt-4 mt-0">
|
|
<p>Make sure your writing is clear, consistent, and localizable by using the following conventions:
|
|
</p>
|
|
<h4>Abbreviations</h4>
|
|
<p>Don't use internal abbreviations in customer-facing copy. </p>
|
|
<p>Don't use apostrophes for plural abbreviations.</p>
|
|
<p>Don't use i.e. or e.g.; they are not localization-friendly.</p>
|
|
<ul>
|
|
<li><strong>Yes:</strong> Router Console, <a href="https://geti2p.org/">geti2p.org</a>,</li>
|
|
<li><strong>No:</strong> RC, DVD's, 1990's, i.e., e.g.</li>
|
|
</ul>
|
|
<h4>Active voice</h4>
|
|
<ul>
|
|
<li><strong>Yes:</strong> Users connect to I2P with the Router Console.</li>
|
|
<li><strong>No:</strong> User connecting to I2P is made possibly by the Router Console
|
|
.</li>
|
|
</ul>
|
|
<h4>Bold</h4>
|
|
<p>Use bold text to draw the reader's eye to key phrases and statements in your email and web content. For product copy or help articles, use bold for static UI elements like menu items, buttons, screen headings, and anything else you want to call attention to. </p>
|
|
<p>If you need to bold an element but the UI doesn't support it, for example, in a dialog header or a UI message, you can use italics instead.</p>
|
|
<p>Use italics for fields that might change, like a page name.</p>
|
|
<ul>
|
|
<li><strong>Yes: </strong>Go to <strong>General Configuration</strong> > <strong>User Macros</strong>.</li>
|
|
<li><strong>No:</strong><strong>Go to the settings page and click Configuration.</strong></li>
|
|
</ul>
|
|
<h4>Capitalization</h4>
|
|
<p>Use sentence case in all titles, headings, menu items, labels, and buttons. </p>
|
|
<ul>
|
|
<li><strong>Yes:</strong> Welcome to the new I2P!</li>
|
|
<li><strong>No:</strong> Welcome To The New I2P!</li>
|
|
<li><strong>Double no:</strong> wElcOmE tO tHe nEw I2P!</li>
|
|
</ul>
|
|
<h4>Colons</h4>
|
|
<p>Use colons to introduce a bulleted list or series of steps. Don't use colons at the end of headings.</p>
|
|
<h4>Contractions</h4>
|
|
<p>While we are not using exactly casual language, we want to stay consistent with our friendly voice, so use contractions.</p>
|
|
<ul>
|
|
<li><strong>Yes:</strong> Can't, don't, it's</li>
|
|
<li><strong>No:</strong> Cannot, can not, it is</li>
|
|
</ul>
|
|
<h4>Direct quotes</h4>
|
|
<p>Quote with quotes, not italics.</p>
|
|
<ul>
|
|
<li><strong>Yes </strong>: "I2P is the best software ever!" said Mike.</li>
|
|
<li><strong>No</strong>: <em>I2P is just ok. </em> said Mike.</li>
|
|
</ul>
|
|
<h4>Exclamation marks</h4>
|
|
<p>Avoid exclamation marks! They should only be used for exciting or new things! At the most, there should only be one exclamation mark per page!</p>
|
|
<h4>Gender</h4>
|
|
<p>When possible, avoid gendered pronouns. If you can't, then <em>they</em> or <em>their</em> is preferable to <em>his or her</em> or <em>he or she</em>.</p>
|
|
<ul>
|
|
<li><strong>Much yes:</strong> Ask your mentor to show you around the router console.</li>
|
|
<li><strong>Yes:</strong>Ask your mentor if they can show you around the router console.</li>
|
|
<li><strong>No:</strong> Ask your mentor if he or she can add you to the instance.</li>
|
|
</ul>
|
|
<h4>Instructions</h4>
|
|
<p>Use different verbs depending on what you're telling the user to do:</p>
|
|
<p><strong>Yes</strong>:<br></p>
|
|
<ul>
|
|
<li>Choose: the user is picking from one of several option</li>
|
|
<li>Select or click: the user is clicking or tapping something</li>
|
|
<li>Tap, swipe: these are tailored for mobile</li>
|
|
<li>Go to, head to: okay for the first item in a menu </li>
|
|
</ul><strong>No:</strong>
|
|
<ul>
|
|
<li>Hit</li>
|
|
<li>Push</li>
|
|
<li>Poke</li>
|
|
</ul>
|
|
<h4>Italics</h4>
|
|
<p>Use italics for emphasis, citations, or defining a term. You can also use it for UI elements that might change, like a field name or user input.
|
|
</p>
|
|
<p>You can also use italics in places where you would normally use bold but the UI doesn't support it. For example, in a dialog header or UI message.
|
|
</p>
|
|
<p>Don't use italics if the item is also a hyperlink.
|
|
</p>
|
|
<p>See bold for more information about how to format UI elements.
|
|
</p>
|
|
<ul>
|
|
<li><strong>Yes:</strong> According to the 2008<em> IT Unplugged</em> report, IT is really unplugged!</li>
|
|
<li><strong>Yes</strong>: For example, if you create a metric called <em>Time to resolution</em>, other projects can create metrics with that name.</li>
|
|
</ul>
|
|
<ul>
|
|
<li><strong>No: </strong> To learn more, see the <em><u>I2P Documentation</u></em>.</li>
|
|
<li><strong>No</strong>: In the Router Console, select <em>Addressbook</em> > <em>Contact</em>.</li>
|
|
</ul>
|
|
<h4>Lists</h4>
|
|
<p>Use lists to draw the reader's eye and make items easier to scan and follow. Use proper punctuation in your items if they are complete sentences. Try to limit lists to six items or fewer. If you need more items, see if you can split the list into multiple lists.</p>
|
|
<h3>Bulleted</h3>
|
|
<p>Use bulleted lists for options, or a list where the order of the items doesn't matter. Phrase each item in a parallel way. If the bullets complete the introductory sentence, start the fragments with lowercase and skip the periods.</p>
|
|
<p><strong>Yes:</strong></p>
|
|
<p>Due to security concerns, everyone is now required to:</p>
|
|
<ul>
|
|
<li>wear an identification tag in the building</li>
|
|
<li>identify themselves when answering the phone</li>
|
|
<li>use their identification tag to enter or leave before 7 AM and after 6 PM</li>
|
|
<li>alert security if a suspicious package is found</li>
|
|
</ul>
|
|
<p><strong>No:</strong></p>
|
|
<p>Due to security concerns, everyone is now required to follow the regulations below:</p>
|
|
<ul>
|
|
<li>Wear an identification tag when in the company building</li>
|
|
<li>Employees who answer the phone must first identify themselves</li>
|
|
<li>Entering the building before 7 AM and after 6 PM requires that employees use their identification tag to enter or leave the building</li>
|
|
<li>When opening all packages, alert security if the package is suspicious.</li>
|
|
</ul>
|
|
<h3>Numbered</h3>
|
|
<p>Use numbered lists for tasks, or lists where the order of the items matters. Unlike with bulleted lists, always capitalize the first word in each item and end the item with a period.</p>
|
|
<p>You don't need to create a list for tasks that have 2 or fewer steps.</p>
|
|
<p>To add a new user macro:</p>
|
|
<ol>
|
|
<li>Go to Settings > <strong> General Configuration </strong> > <strong> User Personas. </strong></li>
|
|
<li>Choose <strong>Create a User Persona.</strong></li>
|
|
<li>Enter the persona details.</li>
|
|
</ol>
|
|
<<h4>Numbers</h4>
|
|
<p>Write out numbers one through ten. After ten, you can use 11, 12, 108, and so on. </p>
|
|
<h4>Oxford comma</h4>
|
|
<p>Use the Oxford or serial comma to offset the final item in a list. </p>
|
|
<ul>
|
|
<li><strong>Yes:</strong> We use sentence case in all titles, headings, menu items, and buttons.</li>
|
|
<li><strong>No:</strong> We use sentence case in all titles, headings, menu items and buttons.</li>
|
|
</ul>
|
|
<h4>Periods (full stops)</h4>
|
|
<p>Use only one space after a period. Avoid periods in headers, titles, tooltips, field descriptions, and menu names. Use to complete description text in the product, messages, and notifications. Don't use them in a bulleted list unless the list item is a complete sentence. </p>
|
|
<ul>
|
|
<li><strong>Yes:</strong> Public room</li>
|
|
<li><strong>No:</strong> Public room</li>
|
|
</ul>
|
|
<h4>Possessives</h4>
|
|
<p>Use ’s to show possession, even if the word ends in s. </p>
|
|
<ul>
|
|
<li><strong>Yes</strong>: James's book</li>
|
|
<li><strong>Yes</strong>: a week's time</li>
|
|
<li><strong>No</strong>: James' book</li>
|
|
</ul>
|
|
<h4>Pronouns</h4>
|
|
<p>In most cases, second person is best. Exceptions can be made for specific types of writing, such as whitepapers and press releases.</p>
|
|
<p>Not sure whether it's <em>My projects</em> or <em>Your projects</em>? For best results, avoid using <em>mine</em>, <em>my</em>, or <em>your</em> in UI copy.</p>
|
|
<p>If you need to use <em>mine</em>, <em>my</em>, or <em>your</em>, the rule of thumb is to think of the UI as a conversation between the system and the user.</p>
|
|
<p>If the system is presenting information to the user, such as in a dialog box, then <em>your</em> is more appropriate, because it's like saying "Here are your things", or "What would you like to do?"<br>If the user is performing an action, such as clicking a button or a link, then <em>mine/my</em> is more appropriate, because it's like saying "Show me my stuff!".</p>
|
|
<ul>
|
|
<li><strong>Yes</strong>: I2P will change your life.</li>
|
|
<li><strong>Yes</strong>: Your team will like using I2P.</li>
|
|
<li><strong>No</strong> : People like using I2P.</li>
|
|
</ul>
|
|
<h4>Quotation marks</h4>
|
|
<p>Use double quotes (") for a direct quote. For UI elements, page titles, and other objects, use bold text or italics as appropriate. </p>
|
|
<p>Because we write in US English, punctuation goes inside the quotation marks.</p>
|
|
<ul>
|
|
<li><strong>Yes:</strong> "We have big things planned for the coming year," said Mike and Scott.</li>
|
|
<li><strong>Yes</strong>: He called quokkas "the cutest animal ever."</li>
|
|
<li><strong>No:</strong> Add a comment to the <u>"Team processes"</u> page.</li>
|
|
<li><strong>No</strong>: The shark said "Surfers are delicious".</li>
|
|
</ul>
|
|
<h4>Style</h4>
|
|
<p>Five great guidelines for clear, concise writing, courtesy of George Orwell:</p>
|
|
<ol>
|
|
<li>Don't use a metaphor, simile, or other figure of speech that you see. </li>
|
|
<li>Don't use a long word if a shorter one will do.</li>
|
|
<li>If you can omit a word, do it.</li>
|
|
<li>Use active voice.</li>
|
|
<li>Don't use foreign phrases, scientific nomenclature, or jargon if there's an everyday word you can use instead.</li>
|
|
</ol>
|
|
<h4>Titles and headings</h4>
|
|
<p>Use sentence case. Don't use bold, italics, or standard punctuation in headings. It's ok to use question marks and exclamation points if they fit the criteria for those two marvelous pieces of punctuation. </p>
|
|
<ul>
|
|
<li>Capitalize the first word of a title or heading (sentence case)</li>
|
|
<li>Capitalize proper nouns and any trademarked names (products, countries, people's names, etc...)</li>
|
|
<li>Don't use full stops</li>
|
|
</ul>
|
|
<h3>Articles</h3>
|
|
<p>The use of articles (the, a, an) in headings depends on whether the message is conversational or action-based microcopy. Avoid articles in buttons and labels.
|
|
</p>
|
|
<h3>Conversational headings and subheadings</h3>
|
|
<p>In more conversational sections of the interface, like Home cards, marketing copy, and empty states, use articles. It makes the language more approachable and helps understanding when introducing new, complex concepts.</p>
|
|
<h4>Documentation</h4>
|
|
<p>Phrase documentation H1s with an action verb. Don't use gerunds or questions.</p>
|
|
<ul>
|
|
<li><strong>Yes:</strong> Create a page</li>
|
|
<li><strong>No:</strong> Creating a page; How do I create a page?</li>
|
|
</ul>
|
|
<h4>UI elements</h4>
|
|
<ul>
|
|
<li>Use sentence case, even if the UI element does not</li>
|
|
<li>Use bold to call out the UI element in a step. Don't bold the >.</li>
|
|
<li>If the UI element has an icon, use both the name and the icon. </li>
|
|
</ul>
|
|
<p>Go to<strong> More ••• </strong>><strong> Link issues</strong>.</p>
|
|
<h4>US English</h4>
|
|
<p>We write with US English spelling and punctuation. Developers should code in US English.</p>
|
|
<ul>
|
|
<li><strong>Yes:</strong> What kind of cookie would you like with your coffee, friend?</li>
|
|
<li><strong>No:</strong> Which biscuit do ya want with your cuppa, mate?</li>
|
|
</ul>
|
|
|