From 650320bcd1345e38e861de76553cc69882d732ca Mon Sep 17 00:00:00 2001 From: Francesco Domenico Servidio Date: Wed, 14 Feb 2024 12:45:01 +0100 Subject: [PATCH] Updated Style Guide - Edited most of non-Nordic mentions. - Edited line breaks to match Nordic Style. Signed-off-by: Francesco Domenico Servidio --- docs/acronyms.md | 97 +++++------ docs/bias-free-communication.md | 84 +++++----- docs/brand-voice-above-all-simple-human.md | 41 ++--- docs/capitalization.md | 186 +++++++++------------ docs/punctuation/apostrophes.md | 23 --- styleguide/Makefile | 20 +++ styleguide/conf.py | 56 +++++++ styleguide/index.rst | 20 +++ styleguide/make.bat | 35 ++++ 9 files changed, 306 insertions(+), 256 deletions(-) delete mode 100644 docs/punctuation/apostrophes.md create mode 100644 styleguide/Makefile create mode 100644 styleguide/conf.py create mode 100644 styleguide/index.rst create mode 100644 styleguide/make.bat diff --git a/docs/acronyms.md b/docs/acronyms.md index 0043c8237..b8c9be306 100644 --- a/docs/acronyms.md +++ b/docs/acronyms.md @@ -1,100 +1,85 @@ ---- -title: Acronyms - Microsoft Style Guide -author: pallep -ms.author: pallep -ms.date: 01/19/2018 -ms.topic: article -ms.prod: non-product-specific ---- - # Acronyms -Acronyms -and abbreviations can have an adverse effect on clarity, voice, and -SEO. Although some acronyms are widely understood and preferred to the -spelled-out term, others aren't well known or are familiar only to a -specific group of customers. +Acronyms and abbreviations can have an adverse effect on clarity, voice, and SEO. +Although some acronyms are widely understood and preferred to the spelled-out term, others aren't well known or are familiar only to a specific group of customers. ## Don't create acronyms from product or feature names -Always -spell out Microsoft product and feature names. +Always spell out Nordic Semiconductor product and feature names. ## Only use acronyms that your audience is familiar with -The A–Z word list has guidelines for many common acronyms, and some acronyms are so widely used that they're in *[The American Heritage Dictionary](https://ahdictionary.com/).* +The A–Z word list has guidelines for many common acronyms, and some acronyms are so widely used that they're in *[The American Heritage Dictionary](https://ahdictionary.com/).* ## If you have to use an acronym, also spell out the term for clarity -In -general, include the acronym in parentheses following the spelled-out -term. On subsequent mentions in the same article, page, or screen, you can -use the acronym without spelling it out. +In general, include the acronym in parentheses following the spelled-out term. +On subsequent mentions in the same article, page, or screen, you can use the acronym without spelling it out. + -Some acronyms, like *USB, FAQ,* and *URL,* are more well known than the spelled-out term. Don't spell out the term if the acronym is listed in *[The American Heritage Dictionary](https://ahdictionary.com/)* or if the A–Z word list -says to use the acronym without spelling it out. If you're sure your -audience is familiar with an acronym, it's OK to use it without spelling -it out. +Some acronyms, like *USB, FAQ,* and *URL,* are more well known than the spelled-out term. +Don't spell out the term if the acronym is listed in *[The American Heritage Dictionary](https://ahdictionary.com/)* or if the A–Z word list says to use the acronym without spelling it out. +If you're sure your audience is familiar with an acronym, it's OK to use it without spelling it out. -**Examples** -Conversation as a platform (CaaP) has the potential to make booking a flight as easy as sending a text message. Developers are also looking to CaaP to make computing more accessible to users of all abilities. -Learn how to connect a USB device to your Microsoft Surface. +**Examples** +Conversation as a platform (CaaP) has the potential to make booking a flight as easy as sending a text message. +Developers are also looking to CaaP to make computing more accessible to users of all abilities. + +TODO ## Don't introduce acronyms that are used just once -If -an acronym will appear only once in your content, just spell out the -term. Don't introduce it in parentheses after the spelled-out version. +If an acronym will appear only once in your content, just spell out the term. +Don't introduce it in parentheses after the spelled-out version. **Exception** It's OK to use both the spelled-out term and the acronym if both are needed for SEO, even if the acronym is used only once. ## Be careful with acronyms in titles and headings -Avoid -using an acronym for the first time in a title or heading, unless it's a -keyword that you need to place in the title or heading for SEO. If the -first use of the acronym is in a title or heading, introduce the acronym -(in parentheses, following the spelled-out term) in the following body -text. +Avoid using an acronym for the first time in a title or heading, unless it's a keyword that you need to place in the title or heading for SEO. +If the first use of the acronym is in a title or heading, introduce the acronym (in parentheses, following the spelled-out term) in the following body text. + ## Lowercase the spelled-out term -Lowercase -all words in the spelled-out form of an acronym except for proper -nouns. The names of many protocols and specifications are considered -proper nouns and are capitalized when spelled out. +Lowercase all words in the spelled-out form of an acronym except for proper nouns. +The names of many protocols and specifications are considered proper nouns and are capitalized when spelled out. -**Examples** -infrastructure as a service (IaaS) -dynamic-link library (DLL)
High-Definition Multimedia Interface (HDMI) +**Examples** +infrastructure as a service (IaaS) +dynamic-link library (DLL) +High-Definition Multimedia Interface (HDMI) ## Use *a* or *an,* depending on pronunciation Which article (*a* or *an*) you use depends on whether you pronounce the acronym like a word or pronounce each letter. -**Examples** -a DLL -an ISP -a URL +**Examples** +a DLL +an ISP +a URL an SQL database **Add *s* to make an acronym plural** -Form the plural of an acronym like you would any other noun. If the acronym stands for a singular noun, add a lowercase *s* to make it plural. If an acronym stands for a plural noun, don’t add an *s.* +Form the plural of an acronym like you would any other noun. +If the acronym stands for a singular noun, add a lowercase *s* to make it plural. +If an acronym stands for a plural noun, don’t add an *s.* -**Examples** -three APIs -Microsoft Foundation Classes (MFC) +**Examples** +three APIs +TODO ## Avoid the possessive form Unless an acronym refers to a person or an organization, avoid using the possessive form. -**Examples** -the IDE enhancements -the purpose of the FAQ +**Examples** +the IDE enhancements +the purpose of the FAQ the CEO’s blog -**Global tip** In machine-translated content, be careful with acronyms that form common English words, like *RAM.* If the acronym appears outside of the parentheses and without the spelled-out version, it might be translated incorrectly. +**Global tip** In machine-translated content, be careful with acronyms that form common English words, like *RAM*. +If the acronym appears outside of the parentheses and without the spelled-out version, it might be translated incorrectly. **See also** [Bits and bytes term collection](~/a-z-word-list-term-collections/term-collections/bits-bytes-terms.md), [Units of measure term collection](~/a-z-word-list-term-collections/term-collections/units-of-measure-terms.md) diff --git a/docs/bias-free-communication.md b/docs/bias-free-communication.md index ad48f83c1..fe1fefd15 100644 --- a/docs/bias-free-communication.md +++ b/docs/bias-free-communication.md @@ -1,15 +1,6 @@ ---- -title: Bias-free communication - Microsoft Style Guide -author: pallep -ms.author: pallep -ms.date: 09/13/2019 -ms.topic: article -ms.prod: non-product-specific ---- - # Bias-free communication -Microsoft technology reaches every part of the globe, so it's critical that all our communications are inclusive and diverse. +Nordic Semiconductor technology reaches every part of the globe, so it's critical that all our communications are inclusive and diverse. **Use gender-neutral alternatives for common terms.** @@ -23,14 +14,15 @@ Microsoft technology reaches every part of the globe, so it's critical that all | synthetic, manufactured | manmade | | workforce, staff, personnel | manpower | -**Don't use *he, him, his, she, her,* or *hers* in generic references.** Instead: -- Rewrite to use the second person (*you*). +**Don't use *he, him, his, she, her,* or *hers* in generic references.** Instead: +- Rewrite to use the second person (*you*). - Rewrite the sentence to have a plural noun and pronoun. -- Use *the* or *a* instead of a pronoun (for example, "the document"). +- Use *the* or *a* instead of a pronoun (for example, "the document"). - Refer to a person's role (*reader, employee, customer,* or *client,* for example). -- Use *person* or *individual.* +- Use *person* or *individual.* -If you can't write around the problem, it's OK to use a plural pronoun (*they, their,* or *them*) in generic references to a single person. Don't use constructions like *he/she* and *s/he.* +If you can't write around the problem, it's OK to use a plural pronoun (*they, their,* or *them*) in generic references to a single person. +Don't use constructions like *he/she* and *s/he.* | **Use this** | **Not this** | @@ -41,43 +33,40 @@ If you can't write around the problem, it's OK to use a plural pronoun (*they, t | To call someone, select the person's name, select **Make a phone call**, and then choose the number you'd like to dial. | To call someone, select his name, select **Make a phone call**, and then select his number. | | If you want to call someone who isn't in your Contacts list, you can dial their phone number using the dial pad. | If you want to call someone who isn't in your Contacts list, you can dial his or her phone number using the dial pad. | -**When you're writing about a real person, use the pronouns that person prefers,** whether it's *he, she, they,* -or another pronoun. It's OK to use gendered pronouns (like *he, she, his,* and *hers*) when you're -writing about real people who use those pronouns themselves. +**When you're writing about a real person, use the pronouns that person prefers,** whether it's *he, she, they,* or another pronoun. +It's OK to use gendered pronouns (like *he, she, his,* and *hers*) when you're writing about real people who use those pronouns themselves. -It's also OK to use gendered pronouns in content such as direct quotations and the titles of works and when gender -is relevant, such as discussions about the challenges that women face in the workplace. -**Examples** -The skills that Claire developed in the Marines helped her move into a thriving technology career. -Anthony Lambert is executive vice president of gaming. With his team and game development partners, -Lambert continues to push the boundaries of creativity and technical innovation. -The chief operating officer of Munson's Pickles and Preserves Farm says, "My great uncle Isaac, who employed -his brothers, sisters, mom, and dad, knew that they—and his customers—were depending on him." -Do you have a daughter? Here are a few things you can do to inspire and support her interest in STEM subjects. +It's also OK to use gendered pronouns in content such as direct quotations and the titles of works and when gender is relevant, such as discussions about the challenges that women face in the workplace. +**Examples** +The skills that Claire developed in the Marines helped her move into a thriving technology career. +Anthony Lambert is executive vice president of gaming. +With his team and game development partners, Lambert continues to push the boundaries of creativity and technical innovation. +The chief operating officer of Munson's Pickles and Preserves Farm says, "My great uncle Isaac, who employed his brothers, sisters, mom, and dad, knew that they—and his customers—were depending on him." +Do you have a daughter? +Here are a few things you can do to inspire and support her interest in STEM subjects. -**In fictitious scenarios, strive for diversity and avoid stereotypes in job roles.** Choose names that reflect -a variety of gender identities and cultural backgrounds. +**In fictitious scenarios, strive for diversity and avoid stereotypes in job roles.** +Choose names that reflect a variety of gender identities and cultural backgrounds. -**In text and images, represent diverse perspectives and circumstances.** Depict a variety of people from all -walks of life participating fully in activities. Be inclusive of gender identity, race, culture, ability, age, -sexual orientation, and socioeconomic class. Show people in a wide variety of professions, educational settings, -locales, and economic settings. Avoid using examples that reflect primarily a Western or affluent lifestyle. -In drawings or blueprints of buildings, show ramps for wheelchair accessibility. +**In text and images, represent diverse perspectives and circumstances.** +Depict a variety of people from all walks of life participating fully in activities. +Be inclusive of gender identity, race, culture, ability, age, sexual orientation, and socioeconomic class. +Show people in a wide variety of professions, educational settings, locales, and economic settings. +Avoid using examples that reflect primarily a Western or affluent lifestyle. +In drawings or blueprints of buildings, show ramps for wheelchair accessibility. -**Be inclusive of job roles, family structure, and leisure activities.** If you show various family groupings, -consider showing nontraditional and extended families. +**Be inclusive of job roles, family structure, and leisure activities.** +If you show various family groupings, consider showing nontraditional and extended families. -**Be mindful when you refer to various parts of the world.** If -you name cities, countries, or regions in examples, make sure -they're not politically disputed. In examples that refer to several -regions, use equivalent references—for example, don't mix -countries with states or continents. +**Be mindful when you refer to various parts of the world.* +If you name cities, countries, or regions in examples, make sure they're not politically disputed. +In examples that refer to several regions, use equivalent references—for example, don't mixcountries with states or continents. -**Don't make generalizations about people, countries, regions, and cultures,** not even positive or neutral generalizations. +**Don't make generalizations about people, countries, regions, and cultures,** not even positive or neutral generalizations. -**Don't use slang,** especially if it could be considered cultural appropriation, such as *spirit animal.* +**Don't use slang.** -**Don't use profane or derogatory terms,** such as *pimp* or *bitch.* +**Don't use profane or derogatory terms.** **Avoid culturally sensitive terms,** such as the terms associated with military or political actions or other historic events and eras. @@ -88,8 +77,11 @@ countries with states or continents. | perimeter network | demilitarized zone (DMZ) | | stop responding | hang | -**Focus on people, not disabilities.** For example, talk about readers who are blind or have low vision and customers with limited dexterity. Don't use words that imply pity, such as *stricken with* or *suffering from.* Don't mention a disability unless it's relevant. For more information, see the [Accessibility term collection](~/a-z-word-list-term-collections/term-collections/accessibility-terms.md). +**Focus on people, not disabilities.** For example, talk about readers who are blind or have low vision and customers with limited dexterity. +Don't use words that imply pity, such as *stricken with* or *suffering from.* +Don't mention a disability unless it's relevant. +For more information, see the [Accessibility term collection](~/a-z-word-list-term-collections/term-collections/accessibility-terms.md). -**Learn more** For more information about writing that conveys respect to all people and promotes equal opportunities, see the [Guidelines for Inclusive Language](https://www.linguisticsociety.org/content/guidelines-inclusive-language "Linguistic Society of America's guidelines for inclusive language") from the Linguistic Society of America. +**Learn more** For more information about writing that conveys respect to all people and promotes equal opportunities, see the [Guidelines for Inclusive Language](https://www.linguisticsociety.org/content/guidelines-inclusive-language "Linguistic Society of America's guidelines for inclusive language") from the Linguistic Society of America. **See also** [Accessibility guidelines and requirements](~/accessibility/accessibility-guidelines-requirements.md), [Global communications](~/global-communications/index.md) diff --git a/docs/brand-voice-above-all-simple-human.md b/docs/brand-voice-above-all-simple-human.md index eb7ef6527..cff9d2315 100644 --- a/docs/brand-voice-above-all-simple-human.md +++ b/docs/brand-voice-above-all-simple-human.md @@ -1,62 +1,53 @@ ---- -title: Microsoft's brand voice : above all, simple and human - Microsoft Style Guide -author: pallep -ms.author: pallep -ms.date: 01/19/2018 -ms.topic: article -ms.prod: non-product-specific ---- - -# Microsoft's brand voice: Above all, simple and human +# Nordic Semiconductor's brand voice: Above all, simple and human There’s *what* we say, our message. And there’s *how* -we say it, our voice. +we say it, our voice. ## What do we mean by voice? -The Microsoft voice is how we talk to people. It’s the interplay of personality, substance, tone, and style. +The Nordic Semiconductor voice is how we talk to people. It’s the interplay of personality, substance, tone, and style. Though our voice is constant regardless of who we’re talking to or what we’re saying, we adapt our tone—from serious to empathetic to lighthearted—to -fit the context and the customer's state of mind. +fit the context and the customer's state of mind. ## Three voice principles -Our voice hinges on crisp simplicity. Bigger ideas and fewer words. Less head, more heart. +Our voice hinges on crisp simplicity. Bigger ideas and fewer words. Less head, more heart. Our voice is: - **Warm and relaxed**—We’re natural. Less formal, more grounded in real, everyday conversations. - Occasionally, we’re fun. (We know when to celebrate.) - - - **Crisp and clear**—We’re to the point. We write for scanning first, reading second. We make it simple above all. - + Occasionally, we’re fun. (We know when to celebrate.) + + - **Crisp and clear**—We’re to the point. We write for scanning first, reading second. We make it simple above all. + - **Ready to lend a hand**—We show customers we’re on their side. We anticipate their real needs and offer great information at just the right time. ## A focus on the customer Talking to our customers in a way -that’s warm and relaxed, crisp and clear, and ready to lend a hand reflects our commitment to empowering +that’s warm and relaxed, crisp and clear, and ready to lend a hand reflects our commitment to empowering people to achieve more. **Style tips** -A few key elements of writing Microsoft’s voice: +A few key elements of writing Nordic Semiconductor’s voice: - **Get to the point fast.** Start with the key takeaway. Put the most important thing in the most noticeable spot. Make choices and next steps obvious. Give people just enough information to make decisions confidently. Don’t get in - the way. - + the way. + - **Talk like a person.** Choose optimistic, conversational language. Use short everyday words, contractions, and sentence-style capitalization. Shun jargon and acronyms. And never miss an opportunity to find a better - word. - + word. + - **Simpler is better.** Everyone likes clarity and getting to the point. Break it up. Step it out. Layer. Short sentences and fragments are easier to scan and read. @@ -64,6 +55,6 @@ A few key elements of writing Microsoft’s voice: **Get started** -For more quick techniques, check out the [Top 10 tips for Microsoft style and voice](~/top-10-tips-style-voice.md). +For more quick techniques, check out the [Top 10 tips for Nordic Semiconductor style and voice](~/top-10-tips-style-voice.md). Remember that writing is a skill. If writing isn't a functional role your team has, consider bringing in expert help. diff --git a/docs/capitalization.md b/docs/capitalization.md index e3a9542c2..7ccf136b1 100644 --- a/docs/capitalization.md +++ b/docs/capitalization.md @@ -1,117 +1,91 @@ ---- -title: Capitalization - Microsoft Style Guide -author: pallep -ms.author: pallep -ms.date: 09/6/2019 -ms.topic: article -ms.prod: non-product-specific ---- - # Capitalization -Microsoft -style uses sentence-style capitalization. That means everything is -lowercase except the first word and proper nouns, which include the -names of brands, products, and services. (Microsoft has more than 500 offerings. To help customers recognize, find, and buy them, reserve capitalization for product and service names.) - -Follow these guidelines in Microsoft content: - - - Use sentence-style capitalization most of the time. That means: - - Capitalize the first word of a sentence, heading, title, UI label (such as - the name of a button or check box), or standalone phrase. - - Capitalize proper nouns. To learn more about proper nouns, see [Nouns and pronouns](~/grammar/nouns-pronouns.md). - - Use lowercase for everything else. - - - Always capitalize the first word of a new sentence. Rewrite sentences - that start with a word that's always lowercase. - - - Don't use all uppercase for emphasis. (It's OK to use italic sparingly for emphasis.) - - - Don't use all lowercase as a design choice. Although all uppercase is used occasionally as a design element, don't use it in text. - - - - - Don't use internal capitalization (such as *AutoScale* or *e-Book*) unless it's part of a brand name. - - - Don't capitalize the spelled-out form of an acronym unless it's a proper noun. - - - When words are joined by a slash, capitalize the word after the slash if the word before the slash is capitalized. - **Examples** - Country/Region - Turn on the On/Off toggle. - - - For information on capitalization in hyphenated compound words see [Hyphens](punctuation/dashes-hyphens/hyphens.md). - -**Learn more** To learn more about capitalization, see [*The Chicago Manual of Style*](http://www.chicagomanualofstyle.org/home.html). If you're not sure whether to capitalize a term, check the A–Z word list and [*The American Heritage Dictionary*](https://ahdictionary.com/). - - -For information about capitalizing UI labels in instructions, see [Formatting text in instructions](~/procedures-instructions/formatting-text-in-instructions.md). +Nordic Semiconductor style uses sentence-style capitalization. +That means everything is lowercase except the first word and proper nouns, which include the names of brands, products, and services. +(To help customers recognize, find, and buy products, reserve capitalization for product and service names.) + +Follow these guidelines in Nordic content: + +- Use sentence-style capitalization most of the time. That means: + - Capitalize the first word of a sentence, heading, title, UI label (such as the name of a button or check box), or standalone phrase. + - Capitalize proper nouns. To learn more about proper nouns, see [Nouns and pronouns](~/grammar/nouns-pronouns.md). + - Use lowercase for everything else. +- Always capitalize the first word of a new sentence. Rewrite sentences that start with a word that's always lowercase. +- Don't use all uppercase for emphasis. (It's OK to use italic sparingly for emphasis.) +- Don't use all lowercase as a design choice. Although all uppercase is used occasionally as a design element, don't use it in text. +- Don't use internal capitalization (such as *AutoScale* or *e-Book*) unless it's part of a brand name. +- Don't capitalize the spelled-out form of an acronym unless it's a proper noun. +- When words are joined by a slash, capitalize the word after the slash if the word before the slash is capitalized. + **Examples** + - Country/Region + - Turn on the On/Off toggle. +- For information on capitalization in hyphenated compound words, see [Hyphens](~/punctuation/dashes-hyphens/hyphens.md). +- Capitalize the first letter of the first word in bulleted or numbered lists, figure callouts, and text in table cells, unless it begins with a command name or other literal computer terms that are not capitalized. +- Capitalize the first letter of the first word following a colon if it starts a complete sentence. +- Capitalize the first letter of the terms "Table", "Section", "Part", "Figure", "Example", "Appendix", "Step", "Version", "Chapter", and "Release" when they are followed by a number or letter. +- Capitalize the first letter of each term that identifies the name of a keyboard key, like Control-C, the F key, Ctrl+Shift+F1. +- Capitalize the second element of a hyphenated compound word in a title or heading unless the first element is a prefix. +- Follow the same capitalization rules as titles and section headings for the first letter of the first word of a title or heading, example captions, figure captions, table captions, and table column headings. + +**What Not to Capitalize** +- Do not capitalize the word "page" in page number descriptions, the "x" in hexadecimal text, dimensions, or processor architectures like "x86" and "x64." +- Do not capitalize placeholders and user-supplied values unless they include proper nouns. +- Maintain the case sensitivity of command and function names and other software elements. + +**Learn more** To learn more about capitalization, see [*The Chicago Manual of Style*](http://www.chicagomanualofstyle.org/home.html). If you're not sure whether to capitalize a term, check the A–Z word list and [*The American Heritage Dictionary*](https://ahdictionary.com/). + +For information about capitalizing UI labels in instructions, see [Formatting text in instructions](~/procedures-instructions/formatting-text-in-instructions.md). ## Sentence-style capitalization in titles and headings -Use sentence-style capitalization in most titles and headings: capitalize -the first word and lowercase the rest. -**Exceptions** Proper nouns, including brand, product, and service names, are always -capitalized. If a title or heading includes a colon, capitalize the first word after it. +Use sentence-style capitalization in most titles and headings: capitalize the first word and lowercase the rest. +**Exceptions** Proper nouns, including brand, product, and service names, are always capitalized. If a title or heading includes a colon, capitalize the first word after it. -Titles of blog posts, documentation articles, and press releases use sentence-style capitalization.
-**Examples** -Watch your favorite HD movies, TV shows, and more -1 TB of cloud storage -Choose the Office version that's right for you -Available for Microsoft partners and commercial and public-sector customers -Can a search engine predict the World Cup winner? -Block party: Communities use Minecraft to create public spaces +Titles of blog posts, documentation articles, and press releases use sentence-style capitalization. +**Examples** +- Watch your favorite HD movies, TV shows, and more +- 1 TB of cloud storage +- Choose the Office version that's right for you +- Available for Microsoft partners and commercial and public-sector customers +- Can a search engine predict the World Cup winner? +- Block party: Communities use Minecraft to create public spaces ## Title-style capitalization -Occasionally, title-style capitalization—capitalizing most words—is appropriate. -For example, product and service names, the names of blogs, book and -song titles, article titles in citations, white paper titles, and titles of people -(*Vice President* or *Director of Marketing*) require title-style capitalization. In a tweet, it's OK -to use title-style capitalization to highlight the name of a quoted article. - -On the rare occasions when title-style capitalization is required, follow these guidelines: - - - Always capitalize the first and last words.
- **Example** - A Home to Go Back To - - - Don't capitalize *a, an,* or *the* unless it's the first word. - **Examples** - Microsoft on the Issues - The Official Microsoft Blog - - - Don't capitalize prepositions of four or fewer letters (such as *on, to, in, up, down, of,* and *for*) unless the preposition is the first or last word. - **Examples** - How to Personalize Windows - To Personalize Windows - Ryse: Son of Rome - Achieving Excellence in the Classroom Through Technology - OneNote Class Notebooks for Teachers - The Teaching Tool You're Looking For - - - Don't capitalize *and, but, or, nor, yet,* or *so* unless it's the first word or the last word. - **Example** - Monitoring and Operating a Private or Hybrid Cloud - - - Capitalize all other words, including nouns, verbs (including *is* and other forms of *be*), adverbs (including *very* and *too*), adjectives, and pronouns (including *this, that,* and *its*). - **Examples** - Enterprise Agility Is Not an Oxymoron - This Is All There Is - Teaching Math Over and Over Again, in Less Time Than Before - - - Capitalize the word after a hyphen if it would be capitalized without the hyphen or it's the last word. - **Examples** - Self-Paced Training for Microsoft Visual Studio - Microsoft Management Console: Five Essential Snap-ins - Five Essential Snap-ins for Microsoft Management Console - Copy-and-Paste Support in Windows Apps - - - Capitalize the first word of labels and terms that appear in - UI and APIs unless they're always lowercase (for example, - *fdisk*). - - - In programming languages, follow the traditional capitalization of keywords and other special terms. +Occasionally, title-style capitalization — capitalizing most words — is appropriate. For example, product and service names, the names of blogs, book and song titles, article titles in citations, white paper titles, and titles of people (*Vice President* or *Director of Marketing*) require title-style capitalization. In a tweet, it's OK to use title-style capitalization to highlight the name of a quoted article. + +On the rare occasions when title-style capitalization is required, follow these guidelines: + +- Always capitalize the first and last words. + **Example** + - A Home to Go Back To +- Don't capitalize *a, an,* or *the* unless it's the first word. + **Examples** + - Microsoft on the Issues + - The Official Microsoft Blog +- Don't capitalize prepositions of four or fewer letters (such as *on, to, in, up, down, of,* and *for*) unless the preposition is the first or last word. + **Examples** + - How to Personalize Windows + - To Personalize Windows + - Ryse: Son of Rome + - Achieving Excellence in the Classroom Through Technology + - OneNote Class Notebooks for Teachers + - The Teaching Tool You're Looking For +- Don't capitalize *and, but, or, nor, yet,* or *so* unless it's the first word or the last word. + **Example** + - Monitoring and Operating a Private or Hybrid Cloud +- Capitalize all other words, including nouns, verbs (including *is* and other forms of *be*), adverbs (including *very* and *too*), adjectives, and pronouns (including *this, that,* and *its*). + **Examples** + - Enterprise Agility Is Not an Oxymoron + - This Is All There Is + - Teaching Math Over and Over Again, in Less Time Than Before +- Capitalize the word after a hyphen if it would be capitalized without the hyphen or it's the last word. + **Examples** + - Self-Paced Training for Microsoft Visual Studio + - Microsoft Management Console: Five Essential Snap-ins + - Five Essential Snap-ins for Microsoft Management Console + - Copy-and-Paste Support in Windows Apps +- Capitalize the first word of labels and terms that appear in UI and APIs unless they're always lowercase (for example, *fdisk*). +- In programming languages, follow the traditional capitalization of keywords and other special terms. **See also** [Formatting titles](~/text-formatting/formatting-titles.md) diff --git a/docs/punctuation/apostrophes.md b/docs/punctuation/apostrophes.md deleted file mode 100644 index e03370189..000000000 --- a/docs/punctuation/apostrophes.md +++ /dev/null @@ -1,23 +0,0 @@ -# Apostrophes - -An apostrophe is a punctuation mark used to indicate the omission of letters or figures, the possessive case, or the plural of letters or figures. - -## Use an apostrophe - -Use an apostrophe in the following situations. - -| Situation | Examples | -|-----------|----------| -| **Singular possessive nouns**
Add 's even if the noun ends in an *s, x* or *z*. | insider's guide
the box's contents
the CSS's flexibility | -| **Plural possessive nouns**
If the noun ends in an *s,* add only an apostrophe. | users' passwords | -| **To indicate a missing letter in a contraction** | can't
don't
it's | -| **In place of numerals**
Replaces omitted numerals. | Class of '66 | - -## Don't use an apostrophe - -**Do not** use an apostrophe in the following situations. - -| Situation | Incorrect | Correct | -|-----------|-----------|----------| -| **For the possessive form of *it*** | Replace a formula with **it's** calculated value. | Replace a formula with **its** calculated value. | -| **With a possessive pronoun** | The choice is **your's**. | The choice is **yours**. | diff --git a/styleguide/Makefile b/styleguide/Makefile new file mode 100644 index 000000000..d4bb2cbb9 --- /dev/null +++ b/styleguide/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/styleguide/conf.py b/styleguide/conf.py new file mode 100644 index 000000000..de324920b --- /dev/null +++ b/styleguide/conf.py @@ -0,0 +1,56 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'test-style-guide' +copyright = '2023, Nordic Semiconductor' +author = 'Nordic Semiconductor' + +# The full version, including alpha/beta/rc tags +release = '0.1' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'myst_parser', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] \ No newline at end of file diff --git a/styleguide/index.rst b/styleguide/index.rst new file mode 100644 index 000000000..0b269e010 --- /dev/null +++ b/styleguide/index.rst @@ -0,0 +1,20 @@ +.. test-style-guide documentation master file, created by + sphinx-quickstart on Thu Nov 16 16:56:21 2023. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to test-style-guide's documentation! +============================================ + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/styleguide/make.bat b/styleguide/make.bat new file mode 100644 index 000000000..922152e96 --- /dev/null +++ b/styleguide/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd