Grammar and Style Guidelines for Docker Documentation

--- title: Grammar and style description: Grammar and style guidelines for technical documentation keywords: grammar, style, contribute toc_max: 2 weight: 10 --- Docker documentation should always be written in US English with US grammar. ## Acronyms and initialisms An acronym is an abbreviation you would speak as a word, for example, ROM (for read only memory). Other examples include radar and scuba, which started out as acronyms but are now considered words in their own right. An initialism is a type of acronym that comprises a group of initial letters used as an abbreviation for a name or expression. If you were using the acronym in a spoken conversation, you would enunciate each letter: H-T-M-L for Hypertext Markup Language. ### Best practice - Spell out lesser-known acronyms or initialisms on first use, then follow with the acronym or initialism in parentheses. After this, throughout the rest of your page or document, use the acronym or initialism alone. > ‘You can use single sign-on (SSO) to sign in to Notion. You may need to ask your administrator to enable SSO.’ - Where the acronym or initialism is more commonly used than the full phrase, for example, URL, HTML, you don't need to follow this spell-it-out rule. - Use all caps for acronyms of file types (a JPEG file). - Don't use apostrophes for plural acronyms. ✅URLs ❌URL’S - Avoid using an acronym for the first time in a title or heading. 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 first body text that follows. ## Bold and italics Unless you're referring to UI text or user-defined text, you shouldn't add emphasis to text. Clear, front-loaded wording makes the subject of a sentence clear. ### Best practice - Don't use bold to refer to a feature name. - Use italics sparingly, as this type of formatting can be difficult to read in digital experiences. Notable exceptions are titles of articles, blog posts, or specification documents. ## Capitalization Use sentence case for just about everything. Sentence case means capitalizing only the first word, as you would in a standard sentence. The following content elements should use sentence case: - Titles of webinars and events - Headings and subheadings in all content types - Calls to action - Headers in boxed text - Column and row headers in tables - Links - Sentences (of course) - Anything in the UI including navigation labels, buttons, headings ### Best practice - As a general rule, it's best to avoid the use of ALL CAPITALS in most content types. They are more difficult to scan and take up more space. While all caps can convey emphasis, they can also give the impression of shouting. - If a company name is all lowercase or all uppercase letters, follow their style, even at the beginning of sentences: DISH and bluecrux. When in doubt, check the company's website. - Use title case for Docker solutions: Docker Extensions, Docker Hub. - Capitalize a job title if it immediately precedes a name (Chief Executive Officer Scott Johnston). - Don't capitalize a job title that follows a name or is a generic reference (Scott Johnston, chief executive officer of Docker). - Capitalize department names when you refer to the name of a department, but use lower case if you are talking about the field of work and not the actual department. - When referring to specific user interface text, like a button label or menu item, use the same capitalization that’s displayed in the user interface. ## Contractions A contraction results from letters being left out from the original word or phrase, such as you're for you are or it's for it is. Following our conversational approach, it's acceptable to use contractions in almost all content types. Just don't get carried away. Too many contractions in a sentence can make it difficult to read. ### Best practice - Stay consistent - don't switch between contractions and their spelled-out equivalents in body copy or UI text.

This section outlines the grammar and style guidelines for Docker documentation, emphasizing US English usage. It covers acronyms and initialisms, recommending spelling them out on first use unless commonly known. It also provides guidelines on using bold and italics, avoiding excessive emphasis, and using sentence case for titles, headings, and UI elements. The document also permits contractions for a conversational tone but advises consistency in their use.