Google Style Guides. Every major open-source project has its own style guide: a set of conventions (sometimes arbitrary) about how to write code for that project. It is much easier to understand a large codebase when all the code in it is in a consistent style. “Style” covers a lot of ground, from “use camelCase for variable names” to “never use global variables” to “never use exceptions.” · Follow our gender-neutral pronoun guidance. Avoid being too culturally specific to the US. Be mindful when referring to specific holidays (see also the word list entry for the holidays), cultural · What is a writing style guide? A style guide is a collection of conventions for writing for an industry, brand or project
Google C++ Style Guide
We write our developer documentation in US English, but some of it is translated into languages other than English or is read by developers for whom English is not their primary language. Write with localization, translation, and internationalization in mind. The following list defines these terms:. For more information, see Language localization. The shorter the sentence, the easier it is to translate. English sentences can be shorter in length than other languages, google writing style guide, so an English sentence of average length might result in a long sentence when translated.
Longer sentences can impair understanding, cause rendering issues on the page or product interface, lengthen translation time, and increase translation and review costs. Avoid phrasal verbs when possible. A phrasal verb combines multiple words to form a single verb phrase.
These verbs are also known as compound verbs. Try to substitute a simpler verb first. There might not be a better verb; for example, a few exceptions to this rule include set uplog inand sign in. Recommended: This document uses the following terms:.
Not recommended: This document makes use of the following terms:. Don't use too many modifiers, google writing style guide. In particular, don't use more than two nouns as modifiers of another noun.
Recommended: A cloud-native DevSecOps pipeline in a hybrid environment. Not recommended: A hybrid cloud-native DevSecOps pipeline, google writing style guide. Don't misplace modifiers. For example, place a word like only immediately before the noun or verb that it relates to. Recommended: Developers need to apply for only one token. Not recommended: Developers only need to apply for one token. Don't omit relative pronouns.
To provide clarity and to avoid ambiguity, use relative pronouns such as google writing style guide and google writing style guide. For more information see Optional pronouns. Recommended: Running in a hybrid environment means that some of your processing happens on Google Cloud and other processing remains on-premises. Not recommended: Running in a hybrid environment means some of your processing happens on Google Cloud and other processing remains on-premises.
Clarify antecedents. Using pronouns can get tricky when translators are working with small, unconnected strings of text. Help them out by making things as clear as possible. For example, if a pronoun is ambiguous, then replace it with the appropriate noun. Recommended: If you use the term green beer in an ad, then make sure that the ad is targeted. Not recommended: If you use the term green beer in an ad, then make sure that it's targeted. If you use a particular term for a particular concept in one place, then use that exact same term elsewhere, google writing style guide, including the same capitalization.
If you use different names for the same thing, translators might think you're referring to different concepts, and thus might use different translations.
Inconsistency in terminology and phrasing can greatly increase translation costs, particularly when translation memory and machine translations are used as first steps in translation. You're not writing for your culture. Write with inclusivity in mind. For google writing style guide information, see Writing inclusive documentation. Avoid referring to seasons.
For more information, see Expressing divisions of the year. Send feedback Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4, google writing style guide.
For details, see the Google Developers Site Policies. Key resources. General principles. Language and grammar. Formatting and organization. Computer interfaces. HTML and CSS. Names and naming. The following list defines these terms: Localization: Adapting a product and its google writing style guide documentation for a specific country. This process involves more than translation—for example, google writing style guide, using local currencies or units of measurement.
Translation: Translating one language to another language. This process might involve localization, but the two terms aren't synonymous with one another. Internationalization: Designing a product and its associated documentation to minimize the localization effort—for example, placing all UI strings in a separate file to simplify translation. General dos and don'ts Use present tense. Write dates and times in unambiguous and clear ways.
Use screenshots and text in figures sparingly. For more information, see Figures and other images. Use qualifying nouns for technical keywords. For example, when referring to a file called example.
yamlcall it the example. yaml file and not example. yaml by itself. For more information, see Keywords. Provide context. Don't assume that the reader already knows what you're talking about. Avoid negative constructions when possible. Consider whether it's necessary to tell the user what they can't do instead of what they can. Avoid directional language for example, above or below in procedural documentation. For more information, see UI elements and interaction. Write short, clear, and precise sentences The shorter the sentence, the easier it is to translate.
Use active voice. The subject of the sentence is the person or thing performing the action. With passive voice, it's often hard for readers to figure out who's supposed to do something. For more information, see Active voice. Address the reader directly. Use youinstead of the user or they.
For more information, see Google writing style guide person and first person. Use a simple word. For example, don't use words like commence when you mean start or begin. Don't use consequently when you mean so. Don't use words like utilize or leverage when you mean use. Use a single google writing style guide when it conveys the same idea as a phrase. For example, don't use a phrase like a number of when you can use some or many. Recommended: This document uses the following terms: Not recommended: This document makes use of the following terms: Define abbreviations.
Abbreviations can be confusing out of context, and they don't translate well. Spell things out whenever possible, at least the first time that you use a given term. Google writing style guide more information, see Abbreviations.
Recommended: A cloud-native DevSecOps pipeline in a hybrid environment Not recommended: A hybrid cloud-native DevSecOps pipeline Don't misplace modifiers. Use helper words. Helper words, such as ifthenand ofare frequently left out of conversational English. Use these words to avoid ambiguity. Be consistent If you use a particular term for a particular concept in one place, then use that exact same term elsewhere, including the same capitalization.
Don't use the same word to mean different things. In particular, avoid using the same word as both a noun and a verb in close proximity.
For examples of the multiple-meanings issue, see the word list entries for once and since. Use standardized phrases for frequently used sentences, introductory phrases, and other common tasks. For examples, see introducing linksintroducing outputand introducing code samples.
JavaScript Style Guides: What are they and which one to use?
, time: 6:11blogger.com Content Style Guide - blogger.com
· Google Developer Documentation Style Guide, published online by Google. Provides a set of editorial guidelines for anyone writing developer documentation for Google-related projects. The IBM Style Guide: Conventions for Writers and Editors, , [16] and Developing Quality Technical Information: A Handbook for Writers and Editors, , [17] from IBM Press · Follow our gender-neutral pronoun guidance. Avoid being too culturally specific to the US. Be mindful when referring to specific holidays (see also the word list entry for the holidays), cultural Google Python Style Guide 1 Background. Python is the main dynamic language used at Google. This style guide is a list of dos and don’ts for 2 Python Language Rules. Run pylint over your code using this pylintrc. It finds problems that are typically caught by a 3 Python Style Rules. Do not
No comments:
Post a Comment