Style Conventions for Writers and Editors

The Red Hat Technical Writing Style Guide includes guidance for everyday punctuation and grammar, common mistakes and how to avoid them, strategies for translation and global audiences, content design guidance, and a word usage dictionary.

This guide is a public and open source guide. It is reviewed and maintained primarily by Red Hat. Contributions from the wider community are always welcome.

Other resources for technical writing are listed in Chapter 7, Resources. Of these resources, IBM Style ****is available for Red Hat employees to access online, but does not have a wider circulation. Links in this guide to IBM Style are denoted by a padlock icon .

Release 7.1

Maintenance release in June 2025, with some added and updated guidance.

• Added an entry for "as Code". Refer to as Code.

• Added an entry for "code base", to use in preference to "codebase". Refer to code base.

• Added an entry for "edge". Refer to edge.

• Added an entry for "generative AI, gen AI". Refer to generative AI, gen AI.

• Added an entry for "log out of", to use in preference to "log out from". Refer to log out of.

• Added an entry for "print queue", to use in preference to "printer queue". Refer to print queue.

Release 7.0

Major update in November 2024, with extensive added and updated guidance.

• Updated references to IBM Style to include a link, either to the guide or to a specific topic page where relevant. Each link is denoted with a padlock icon, to show that access is currently restricted to IBM and Red Hat employees.

• Removed content that was specific to marketing content. Removed references to AP Style.

• Updated the audience information. Refer to Section 1, “Audience”.

• Updated the resources information. Refer to Chapter 7, Resources.

• Updated guidance to use the simpler phrase "go to" rather than "navigate to", for directing readers to a location. Refer to go to and navigate to.

• Updated guidance on when to use "named" versus "called" to refer to different items. Refer to named and call, called.

• Added a definition of "mission-critical". Refer to mission-critical.

• Other new or updated usage entries: dash, data store/datastore, dialog box, EPUB, hardened, Infrastructure as Code (IaC), lifecycle, secure, sign in/sign-in. Refer to Part II, “Usage Dictionary”.

• Removed usage entries: check, emdash.

• Updated guidance on using "Overview" in a title. Refer to Overview.

• If dark mode is selected, it now persists across web page refreshes.

Release 6.2

Update in February 2024 to provide added or updated guidance and to address reported issues.

• You can use the possessive form of the company name (Red Hat's) to refer to the company itself, not to any products or services. Refer to Section 2.4, “Possessives”.

• Updated guidance about using realistic usernames, and updated some of the username examples. Refer to Using Realistic Usernames.

• Added some clarifications about writing titles, and about the use of titles and captions with tables and images. Refer to Section 3.2, “Heading Styles”.

• Added guidance about referring to Booleans. Refer to Boolean.

• Use "refer to" instead of "see" for references. Refer to refer to.

• Updated terms that relate to 64-bit architecture: 64-bit ARM, 64-bit x86, AArch64, aarch64, AMD64, amd64, ARM64, arm64, Intel 64, x86_64. Refer to Part II, “Usage Dictionary”.

Release 6.1

Update in August 2023 to provide added or updated guidance and to address reported issues. The listed items here now include links to the appropriate sections.

• Updated guidance about writing titles. Refer to Writing Effective Titles.

• Updated using realistic usernames. Refer to Using Realistic Usernames.

• Changed "Homographic Verbs" subsection title to "Avoid May and Should". Refer to Avoid May and Should .

• Adjusted sentence length guideline. Refer to Sentence Length.

• Removed some references that were specific to DocBook.

• Use "team" or "group" instead of "squad". Refer to squad (n.).

• Improved formatting of spacing after tables and of displaying footnotes in dark mode.

Release 6.0

Major update in December 2022 to add further style and grammar guidance:

• Added audience information for this guide.

• Updated guidance about the use of verbs in titles.

• Updated guidance about the use of captions or callouts in figures.

• Words to use with countable nouns.

• Use of "either-or" construction.

• Avoid stating that something is easy to do or to use.

• Use "following" with a noun.

• Avoid hyphenating with an "-ly" suffix: added an example.

• Make a full lead-in sentence to introduce a list.

• Making list items parallel.

• Updated guidance about use of compact lists.

• Avoid a noun followed by an "-ing" word.

• Preposition at the end of a sentence.

• Use straight rather than curly quotation marks.

• Added further examples of slang, idioms, and metaphors to avoid.

• Spacing with a unit of measurement.

• Improved succinctness examples.

• Avoid "there is", "there are".

• Use "this", "that", "these", "those" with a noun.

• Replaced use of "$" as a variable marker in this guide to use angle brackets instead.

• Use of "whether" versus "if".

• New or updated usage entries: like, once, unset, while.

Release 5.1

Minor update in January 2022 to address some reported issues:

• Accessing IBM Style ****online.

• Updated guidance for long commands.

• Updated guidance for referring to object names.

• Updated guidance for non-breaking spaces.

• Updated guidance for punctuation with quotation marks.

• The gerund verb form is no longer required in section titles.

• Pronouncing file or directory names that begin with special characters.

• Avoid "the product allows the user to do xyz".

• Avoid consecutive headings.

• Guidance to refer to UI elements and to other publication titles.

• Clarification that diagram labels use sentence case.

• New or updated usage entries: backend, IaC, number sign, on premise/on-premise, prebaked, unset.

Release 5.0

Major update in July 2021 to align with some recent changes in IBM Style :

• Sentence case is required for captions, legends, and diagram labels.

• Punctuation: Added sections on referring to punctuation marks and names of punctuation marks and special characters.

• Rename Chapter 4 to "Choosing Appropriate Language": expand scope beyond slang and jargon, to cover inclusive language; avoiding ambiguities (moved from Chapter 2 and added more categories); dates and times (AM and PM are now written in uppercase without periods); and numbers.

• Usage A-Z: Various additions and updates. Corrected alphabetical sorting sequence. Moved items that are not literal term entries to an earlier chapter.

• Minor edits so the guide itself conforms with its own advice.