redhat-documentation / supplementary-style-guide Goto Github PK

The general replaceable value format that we are recommending is this: <ip_address>.

However, that is not XML-friendly due to the angle brackets (< >). Investigate an alternative format to recommend when using replaceable values in XML.

• Should the recommendation be just to remove the angle brackets? ip_address
• Or is there another format that is commonly used that we should recommend?

Old IBM guide said to use "host name" two words. New IBM guide says to use "hostname" (unless updating old content that still uses two words).

We still have an entry in the SSG [1] to use two words. Just checking if we want to keep with "host name" two words as is in the SSG now, or if we want to follow the new IBM style guide guidance (and remove the SSG entry). Thoughts?

[1] https://redhat-documentation.github.io/supplementary-style-guide/#host-name

Another writer asked me about what to call a UI element today -- specifically the three dots that we call 'more options' in docs for the console.redhat.com apps. (Many designers/internal people call this the 'kebab' menu, but that's not optimal for localization or our customers.)

As it's a Patternfly UI element, I found my answer in that style guide: https://www.patternfly.org/v4/ux-writing/writing-for-all-audiences/#writing-for-all-abilities

So we don't duplicate all the good work in the Patternfly guide, what if we add a link to those guidelines and a sentence about what's documented there, so writers know where to look? Perhaps in this section or elsewhere: https://redhat-documentation.github.io/supplementary-style-guide/#user-interface-elements

Making this clear will help improve our consistency across various docs projects.

Thoughts?

@leswilliams44 brought up this issue. We have standard boilerplate for Technology Previews. You can find information about that and lots of discussion among a variety of writers and content strategists on The Source:

• Template and guidelines for documenting Technology Preview features - https://source.redhat.com/groups/public/ccs/ccs_wiki/template_and_guidelines_for_documenting_technology_preview_features

Not all writers seem to be aware of this standard language. Do we need to include this in the Supplemental Guide? Is that the right place? Or would it be the FCC guidelines? I hate that writers have to look so many different places for info.

Here's a link to the standard language on the Customer Portal: https://access.redhat.com/support/offerings/techpreview

That portal link probably needs to be rewritten to look more like the boilerplate in the guides.

The language in the 2 places is not exactly the same.

This is our checklist to complete before the first version of the supplementary style guide can go live.

Guide updates

• Add entry for replaceable values (PR #30)
• Add entry for formatting code examples (#38)
• Add entry for long code blocks in procedures (#39)
• Add entry for lead-in sentence for Prereqs and Procedure headings (PR #37)
• Remove empty placeholders (PR #36)
• Edit the guide (@leswilliams44, @jhoyt-rh, others?)
• Remove WIP note in guide - wait until we're closer to releasing before doing this.

Glossary deprecation updates

See glossary deprecation plan for details

• Redirect old glossary doc (GitHub) to new guide (https://github.com/redhat-documentation/glossary-of-terms-and-conventions-for-product-documentation/pull/11)
• Update glossary GitHub repo README to note deprecation and link to new guide
• Contact tooling team for how to redirect or add a deprecation note to glossary on GitLab (Jira opened with tooling team, PR opened in the meantime to add a warning)
• Update Mojo/the Source pages

Communicate new guide availability

• Once live, communicate out through email lists and meetings!

Although not specifically listed in the IBM SG, I perceive "as", when used as a conditional conjunction, to have the same problems as "once" and "since".

For example: "Consequently, the command would fail as the copy source files did not exist on the managed hosts." would be clearer as "Consequently, the command would fail because the copy source files did not exist on the managed hosts.

Of course, "as" has some unambiguous uses, for example "in the way or manner that" and in established phrases, so we'd have to carefully phrase the recommendation to not discourage these.

WDYT?

Internally within RH we offer some flexibility to replace problematic terms and increase inclusive/conscious language. Apparently, this is to accommodate upstream communities' needs and choices.

However, for blacklist/white list, the Conscious Language Project group have agreed to promote this replacement: blocklist / allowlist , which is in line with the ISG.
"blocklist / allowlist - this combination is recommended by the IBM Style Guide and should be used in absence of other considerations"

Speaking with Kartik and Sam about it, we thought an entry for this might be a good idea. Something that tells writers that for consistency, we should use the ISG-recommended option of blocklist / allowlist even though RH has allowed flexibility to replace such terms.

What do you think?

For more information about the Red Hat stance, search for [1] on the Source.
[1] Conscious Language Project: FAQ

The new 2020 IBM style guide allows for contractions in technical documentation (the old version did not). We should consider adding an exception to the SSG to avoid contractions (unless we want to allow them).

Old IBM guidance:

Do not use contractions in technical information.

Contractions can cause difficulty for translation and for users whose primary language is not English. For example, it’s can be interpreted as it is or it has. Contractions can also contribute to an overly informal tone. ...

New IBM guidance:

Contractions are permitted in all types of content. Decide whether they fit the context. Follow these guidelines when you use contractions: ...

Purpose
I've raised this PR to track the use of the ${} format for XML elements (and possibly other code bases that specify elements with angle brackets (<>)). A discussion on the following PR has agreement comments on the use of ${} format for XML snippets versus the use of angle brackets:

#25

Issue
On writing for the JBoss EAP product, I encountered the follow problem when I used the recommended angle brackets for URVs with XML elements:

<principal_claim_key>>

The final appended angle bracket relates to the XML element and not the URV. A user might intentionally delete the additional angle bracket due to its proximity to the URV after the code renders to an HTML format. Visually, the code snippet looks cluttered.

Suggestion
Use the ${} format for URVs in XML elements and for any other code bases that use angle brackets to represent open and closing tags. For example:

<${spring-boot.version}>

Because the IBM Style Guide (IMHO incorrectly) uses "as expected" a lot and I haven't found any written guideline regarding this, I am proposing to add something along the following to the Supplementary style guide:

"as expected" - expectations are relative and do not belong to technical documentation. Use "correctly" or "properly" instead.

How do we keep all these different groups in sync? Jennifer Ciroli, for example, wants to start a group about using less formal language. That seems to be something that we're already working on. At the very least, we need to coordinate with her, so that our recommendations are consistent.

What other groups are there?

[[user-replaced-values]]
== user-replaced-value-in-a-code-block

The code block example in the "user replaced value in a code block" section of the User Replaced Values entry does not include the source data.

I recommend adding the source data to match the XML user replaced value examples later in the guide.

.Example AsciiDoc

[source,bash,subs="+quotes"]

$ oc describe node _<node_name>_

I'm not sure how helpful this guidance is for a couple of reasons:

When looking for style guidance, reference this guide first, because it overrides certain guidance from The IBM Style Guide.

1. Which guidance in particular? Could there be a list?
2. The ISG is far more expansive than the supplemental guide, which you'd expect--the primary guide is going to be more involved than a supplement to it. It seems more reasonable to me to ask writers to refer to the ISG first, and come to the supplemental guide for additional information.

The IBM Style Guide does not include guidelines for prerequisites.

The style council discussed guidance for writing prerequisites in documentation, but no PR was created yet. This issue is just for tracking.

This issue recently popped up as a discussion on the modular documentation gChat, and I realized that we need to create a PR.

The style council, after much discussion and dissension, decided to write prerequisites in the passive voice. The reasoning: Active voice turns prerequisites into procedural steps. E.g. if you want the user to be logged in with Admin permissions when the procedure begins:

Passive: You are logged in with Administrator privileges
vs
Active: Log in with Administrator privileges.

We should have standardized parameter tables with 4 columns: Parameter, Type, Default, Description

Problem: Portal makes tables ugly.

Are tables going to look nicer in Pantheon 2? Ask the CCSOPS team (Dawn Aly).

Reference doc tables (these tables are unnecessarily annoying and confusing with their current format) [Corrected links]:
https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.1/html/configuration_reference/keystone#auth

https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.1/html/overcloud_parameters/compute-nova-parameters

https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.1/html/command_line_interface_reference/acl#acl_delete

From Alex McLeod on OpenStack

This topic has been suggested by @oraNod and @sangeetaraghu
We should consider providing guidance on how to refer to changes to a product that apply form a particular version onward.

There are multiple ways that this can be expressed, and I can see them all over our docs sets. For example
"{FeatureName} is available in {ProductName} version X.Y or later."
"{FeatureName} is available in {ProductName} as of version X.Y."
"{FeatureName} is available in {ProductName} from version X.Y onward."

We should consider recommending a standard way of phrasing this type of statements in our documentation.

Please consider deleting the entry for data center. The same guidance is provided on page 267 of the IBM Style Guide.

Hi,

I'm adding this issue for the group's awareness. (Ingrid suggested that I add it for tracking purposes.)

The IBM Style Guide states that the correct date format in text is: dd Month yyyy (for example, 1 August 2020).

In earlier versions of RHOSP, the way we identify a particular maintenance release is by its release date. (Fortunately, RHOSP has adopted a new convention of incrementing the Z placeholder in the release number: X.y.z > 16.0.2. In later RHOSP versions, dates are no longer used to identify maintenance releases for customers.)

In the navigation pane on the Customer Portal, topic headings that used the IBM Style Guide mandated date format wrapped in an unfortunate way, causing usability issues.[1] For example, this Release Notes topic:

3.2. Red Hat OpenStack Platform 15 Maintenance Release 3 October 2019

...displayed problematically in the nav pane as:

3.2. Red Hat OpenStack Platform
15 Maintenance Release 3
October 2019

The label could be misinterpreted as Maintenance Release 3, October 2019.

Our team agreed that changing the date format and using a special character as a delimiter made the most sense. Our translator saw no L10n concerns.

Our solution is to use the following format:

3.2. Red Hat OpenStack Platform 15 Maintenance Release - October, 3 2019

The above example displays in the nav pane on the Customer Portal as:

3.2. Red Hat OpenStack Platform
15 Maintenance Release -
October 3, 2019

Of course, exactly how the nav pane label wraps depends on screen resolution and browser window font sizes. But these changes help the user experience.

Thanks,
--Greg
[1] nav_pane_wrap_date_issue

We should add entries for what to call these two UI elements, known (informally?) as a hamburger button and kebab icon:

Hamburger button

Kebab icon

I don't think that either of these terms are appropriate for technical docs, and I've seen this come up a few times across CCS, so we should add in guidance.

What I've seen at least for the kebab, is calling it the "Options menu" and then putting an image of the icon afterward. For example:

Click the Options menu and ...

Not sure if "Options menu" is always appropriate, or maybe only if there is no tooltip. But a followup question on this is whether "Options" should be capitalized and/or styled bold like a UI item if it doesn't actually appear as a tooltip, or should it be lower/unstyled since it's not a literal value in the UI?

And is "menu" or "navigation menu" appropriate as a default for the hamburger button?

My first thoughts at guidance to propose:

• If the icon has a tooltip in the UI, use that as the name.
• If the icon doesn't have a tooltip, have a default name for it (TBD - menu / options menu?)
• Only capitalize/bold if the name actually appears as a tooltip on the icon in the UI
• Either way, include an image of the icon after the name for clarity.

Thoughts?

More info on the icons are here: https://en.wikipedia.org/wiki/Hamburger_button

The FCC Guidelines deviate from the IBM Style Guide on how we handle one-step procedures. Here are the IBM SG guidelines:

"If a procedure consists of only one step, present it as a sentence or short paragraph, and do not number it."

We should call this out in the Supplemental Style Guide and send people to the FCC guidelines.

The OpenShift docs have recently moved away from including docker commands, replacing them with podman commands. Users find it confusing to have two sets of commands without clear guidance about the advantage of using one set over the other. In light of recent efforts to de-emphasize docker terminology, unless there is a specific reason to use docker commands, we should use podman commands.

We have a fair amount of guidance around code blocks. I was just reviewing similar information in the IBM Style Guide with members of the IBM Style Council. It looks like they have more guidance than I realized. We probably need someone more technical than I am to check the two sources against each other.

IBM Style Guide versus Red Hat Supplementary Style guide. We have some overlap, but we also have named our guidelines differently. That may be why we couldn’t find the info in the IBM SG in the first place.

• Technical elements (IBM Style guide)

Code and command examples
Command line data entry
Command syntax
Commands
Files and directories
Variables

• Red Hat supplementary style guide

Code examples
User-replaced variables
User-replaced variables for XML

@bergerhoffer said that she could look at this and do a comparison.

Is anyone aware of any guidance (in the IBM style guide or elsewhere in Red Hat, like legal?) to avoid predicting the future in documentation?

Typically at least on OpenShift, we avoid saying things like "This will be fixed in 4.7" or even "This will be removed in the next release". If we have to say something at all, we'd usually opt for something like "This might be removed in a future release."

I'm not sure if there is ever a case where it is appropriate to make a statement of something coming in a specific version. Should we add guidance to the supplementary style guide saying that avoid saying that something will happen in a specific future version?

As discussed in the Feb 24 Style Council meeting:
The IBM Style Guide describes four levels of conversational style (p. 19) ranging from most to least conversational. Based on feedback from Jennifer Ciroli, it seems like a good idea to specify in the supplementary style guide which tone Red Hat writers should aim for in product documentation.
Based on the initial discussion in the Style Council meeting, most people agreed writers should aim for Less Conversational:

Less conversational: Content that is intended for people who are familiar with the product and who
want information about productive use, managing and upgrading, or getting support.

• Get answers now. Search the documentation and posts from the Stack Overflow community, which is actively monitored.
• The jobs in a stage can't pass artifacts to each other.

I propose adding a short section on this topic to the General formatting section.

Does anyone have thoughts? Disagree about which level of conversational style we should promote? Think this topic belongs in a different section of the supplementary style guide?

The older IBM style guide versions were titled "The IBM Style Guide". For the newer versions, it's just called "IBM Style Guide"

Update our references that say "... The IBM Style Guide ..." to "... the IBM Style Guide ..."

Check the following places:

• The actual style guide content
• This repo (readme, etc.)
• Source pages

We need to standardize on the term Development Preview vs Developer Preview.

From Slack, in #ocm-osd-ui, regarding a label for features in OpenShift Cluster Manager - similar to 'Technology Preview': https://coreos.slack.com/archives/C01G3PL29SS/p1626263095090800

Yaakov Selkowitz
Developer Preview or Development Preview?

Alana Fialkoff 4 hours ago
I've unfortunately seen "Dev Preview" written out as both. 🙁 Managed Kafka currently uses "Development Preview," and other resources cite "Developer Preview" instead. Both forms also appear on Red Hat blog posts.
Does CCS have an official convention for which full-length form is correct for "Dev Preview" features?

My gut instinct is to go with "Development Preview" if possible, so that each feature type follows the same Adjective/Qualifier + Preview formula.
Our main concern is selecting whichever option keeps us consistent across product areas. If there isn't an existing convention already, we can set it ourselves.

From CCS Style Council's Gchat:
Andrea Hoffer:
I just noticed the other day that this page uses both, which is confusing: https://source.redhat.com/groups/public/commonreleasetermsonprem
But that if you click its link, it looks to use development preview exclusively.

Also see #81 about Technology Preview.

Questions:

• Development preview or Developer preview ?
• Who would know the official word on that?

Following a decision:

• pass this info back to the UXD team and Alana Fialkoff to put into the UX/Patternfly style guides

The old IBM Style Guide (2015) recommended "life cycle" for a noun (life-cycle as an adjective). This is also the standard for the Corporate Style Guide, the Customer Portal, and all of our legal docs around life cycle.

The new IBM Style Guide (2021) says "lifecycle". Now we need to add an exception the CCS supplemental style guide.

Product-specific terms related to Red Hat Insights:

The following names designate the names of products that are part of The Red Hat insights offering

• Advisor - manages configuration issues that affect availability, stability, performance and security
• Compliance- assess and monitor the compliance of RHEL systems with SCAP security policies
• Drift - provides comparison of your systems' configuration over time to track and analyze changes
• Patch - view all all Red Hat advisories and patch any system with or more advisories
• Policies - notification of changes to systems or pot
• Resource Optimization - monitor your public cloud systems and improve waste management and rightsizing
• Vulnerability - assess and monitor of RHEL infrastructure exposure to common vulnerabilities and exposures

The following terms have been highlighted as relevant to Red Hat Insights, but are not product-specific.
I would recommend that we add them under hte general glossary section

• CVE- common vulnerabilities and exposures
• RBAC - role based access control
• SCAP - security content automation protocol
• PCP - Performance Co-Pilot Documented in RHEL

An update to the EAP terminology and usage guidelines was completed immediately before the supplemental style guide project began. Terminology and usage specific to EAP should be incorporated into the supplemental style guide.

The draft source for the update is here: https://gitlab.cee.redhat.com/bobjohns/draft-content

One additional section should be added regarding EAP subsystems.

Content that duplicates content from the supplemental style guide should not be ported to the new project. Only the EAP-specific terminology and usage should be ported.

Can we please add "Pod" in the "General conventions" section? I see it written as "Pod" (not "pod") in other areas of the guide, but it would be great to have it documented so that folks can quickly find it and see its capitalization.

Carried over from CCS discussion.

We need to:

• Define abstract.
• Determine where in a doc the abstract goes.
• Define short description.
• Differentiate between an abstract and a short description at the module level or adopt a single term if they are both the same.
• Provide style guidelines with examples
• Update existing topics to reflect changes

Problem: We have three separate documents providing some overlapping information and conflicting guidance, and it is not clear to writers which document is the source of truth. The three documents are:

• The Mod Docs Reference
• The style guides (this one and the IBM Style Guide)
• The Asciidoc markup quick reference

To clarify which guide is the source of truth for what type of information, I propose we add the following disclaimer to all three guides. This issue is for this style guide.

In an obvious place, add:
NOTE The link:https://redhat-documentation.github.io/asciidoc-markup-conventions/[AsciiDoc Mark-up Quick Reference] is the source of truth for guidance specific to writing in Asciidoc. The style guides, both the IBM Style Guide and the link:https://github.com/redhat-documentation/supplementary-style-guide/issues[Red Hat supplementary style guide] are the source of truth for output and writing style guidance that is not specific to Modular Documentation guidelines, and the link:https://redhat-documentation.github.io/modular-docs/[Modular Documentation Reference Guide] and templates are the source of truth for all things connected to Modular Documentation, including implementing those guidelines in Asciidoc.

In the AMQ section of the SSG glossary, there are multiple entries using master/slave terminology:

• master-slave group
• master broker
• slave broker

Someone from AMQ should check whether we are still using this terminology in the documentation and update the SSG glossary if needed.

We don't seem to have an official guidance on documenting features in product docs and/or in release notes that have issues due to which those features may not work. If a reader is looking at documentation on a feature and the feature works but with bugs, should we:

• not document the feature at all since it doesn't work? OR...
• document the feature but link to the known issue from the feature docs and the release notes? OR...
• document the feature, make no note of the issue in the feature docs, and only document the issue in the release notes?

If we go with the middle option, should we have guidance on where we should note the bug within the concept, procedure or reference as may be the case.

The current guidelines on Release Notes were merged, but still need to be included. The current master.adoc looks like this:

// Specific documentation types
// include::style_guidelines/specific-doc-types.adoc[leveloffset=+2]

We have an entry for the Red Hat Container Catalog, but it's not the Ecosytem catalog and there is a container images section. It's complicated and I'm not sure what we should call it. The link redirects to https://catalog.redhat.com/software/containers/explore

In Red Hat customer-facing documentation (solutions, articles, CCS guides) the role of Organization Administrator appears several ways.

• Organization Administrator
• organization administrator
• Org Admin (short form)
• org admin (short form)

Because all the variations refer to the same role, we should use the same term for this role.

Customer Portal Examples:
https://access.redhat.com/solutions/17215
https://access.redhat.com/articles/1757953
https://access.redhat.com/articles/customer-service-accounts

Customer Documentation Examples:
Satellite
https://access.redhat.com/documentation/en-us/red_hat_satellite/5.8/html/getting_started_guide/chap-organizations

User Access/RBAC
https://access.redhat.com/documentation/en-us/red_hat_hybrid_cloud_console/2021/html/user_access_configuration_guide_for_role-based_access_control_rbac/assembly-rbac-procedures

IBM Style Guide suggests, "To distinguish whether a noun is a common noun or a proper noun, consider whether the noun refers to any one of many items (common noun) or whether it refers to the specific name of one item (proper noun)."

Because this is the name of a single, specific role that each Red Hat corporate account must have, that suggests the answer is "Organization Administrator / Org Admin".

Per word nerds, we're sticking with "on-premise" despite ISG saying to not use "on-premise", and suggesting to use "on-prem" or "on-premises" instead.

The SSG already has an entry [1] that says to use "on-premise", but let's also add "on-premises" and "on-prem" as incorrect forms.

Perhaps also consider adding on-prem and on-premises as their own entries, with "use it" set to "no".

[1] https://redhat-documentation.github.io/supplementary-style-guide/#on-premise

While migrating the EAP terminology and usage content, I noticed several terms that might belong in other locations, mostly general conventions, but a few to specific other products.

• ActiveMQ, ActiveMQ Artemis (Add to AMQ module?)
• class loader, class loading, class path, CLASSPATH (Add to general conventions "C" module?)
• Customer Portal (Add to general conventions "C" module?)
• Java (Add to general conventions "J" module?)
• keystore (Add to general conventions "K" module?)
• load balance (Add general conventions "L" module?)
• Red Hat AMQ (Add to AMQ module? Add to general conventions "R" module?)
• Red Hat Customer Portal (Add to general conventions "R" module?)
• trust store, truststore (Add to general conventions "T" module?

Terminology for describing objects and fields in Operator documentation should be consistent with Kubernetes wording.

Kubernetes objects: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/
Custom resources: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/

This issue suggests the following documentation conventions:

• Refer to custom resources by type, using bold text for the type name. For example, "...the Infinispan CR".
• Refer to user defined configuration options in custom resources as "fields" where necessary.
• Prefer to put focus on the task than describing fields.

"Specify the number of nodes in the cluster with spec.replicas in your Infinispan CR." - Focuses more on task.
"Set a value for the spec.replicas field to define the number of nodes in the cluster." - Focuses more on the field (product).

For file: supplementary-style-guide/supplementary_style_guide/style_guidelines/graphical-interfaces.adoc

In this topic, the "User interface elements" section contains the following sentence:
"Bold all graphical user interface elements, including, but not limited to, menu names, menu items, button names, and dialog window names."

I am requesting a change for the phrase "dialog window" to something like "windows, wizard pages, and dialog boxes" or something similar. A "dialog window" mixes the names of two different graphical user interface elements.

A dialog box (not dialog) is a different than a window. In the definition that I am most familiar with, a dialog box appears inside of an application window when you do a certain action and frequently asks for a response that you must give before continuing (or you can cancel the dialog box and that cancels the action). A dialog box contains no other navigation--you can either accept or reject the question or you can cancel it with the X. A dialog box might not have a name, just the content of the question/decision. (Caveat: More recently, I have seen some UX information that defines the "must make a choice before continuing" as a modal dialog box.)

A window is the graphical representation of an application, and it might display one or more dialog boxes inside of it as you do various actions. A window contains navigation, such as scroll bars, menus, etc.

We might want to consider adding icons for the "Use it" field. I feel like it can be easy to overlook that something is actually not supposed to be used. People might skim, find the entry, and not look at that field. I think that icons would make it more obvious to know the status of the term at a quick glance.

I feel like we might have discussed this in the past, but can't remember if we purposefully decided against it for some reason or not.

Problem: Links to Red Hat Knowledgebase articles don't always follow normal link guidelines.

For example:

• For more information, see the Knowledgebase article at https://access.redhat.com/solutions/163853. [1]
• If your Apache web server configuration enables SSL security, verify that you enable only the TLSv1 protocol, and disable SSLv2 and SSLv3. This is due to the POODLE SSL vulnerability (CVE-2014-3566). See https://access.redhat.com/solutions/1232413 for details. [2]
• For a non-cloud environment, the disk and file system can be resized. See the following solution for more information: https://access.redhat.com/solutions/199573[3]

[1] https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html-single/performing_a_standard_rhel_installation/index#manual-partitioning_graphical-installation
[2] https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html-single/performing_a_standard_rhel_installation/index#creating-an-installation-source-on-http_prepare-installation-source
[3] https://docs.openshift.com/container-platform/3.9/day_two_guide/docker_tasks.html

The ISG says to put the hyphen in stand-alone, but it appears that most of our products (if not all) have this as one word already. I recommend adding it to the guide as an exception to the ISG.

We should include the recommendations from the Conscious Language Initiative.
Blacklist/whitelist are not included in the SSG but should be.
Master/slave is referred to and should not be.

In the "Release notes" section of the style guide in the "Deprecated functionality" sub-section, two example texts are provided, both of which contain ungrammatical sentences:

• Bug fixes and support is provided through the end of a future life cycle but Red Hat do not implement new feature enhancements.

should read Bug fixes and support are provided through the end of a future life cycle, but Red Hat will not implement new feature enhancements.

• Bug fixes and support are provided through the end of the RHOSP 15 life cycle but Red Hat do not implement new feature enhancements.

should read Bug fixes and support are provided through the end of the RHOSP 15 life cycle, but Red Hat will not implement new feature enhancements.

Also in both the "Deprecation notice" and "Removal notice" templates, the sentence After which, no new feature enhancements are made. seems like a sentence fragment to me despite the comma usage. At the very least, it seems like an awkward construction to my ears. Maybe replace After which with After this point and are made with will be made.

I can make these changes if others agree that these are legitimate issues.

https://redhat-documentation.github.io/supplementary-style-guide/#user-replaced-values

I recommend that user-replaced variables not be italicized because the markup and rendering can be very messy if a code block or CLI example contains strings that begin with __.

See Vladimir Slavik's on my blog post, AsciiDoc Workarounds.

I think that we need to add this admonition to the Supplementary Style Guide: Avoid self-referential descriptions. We have them all over our guides, and they are content focused, not customer focused. Anytime you write something like this, you're taking customers out of their mindset and forcing them to think like us.

DITA Best Practices (https://www.amazon.com/DITA-Best-Practices-Roadmap-Architecting/dp/0132480522) has great guidance on this:

Avoid Writing Short Descriptions That Are Self-Referential
No one likes a narcissist, so avoid short descriptions that start with language that makes the topic the focus of the short description. For example, avoid the following phrasing:

• “This topic describes....”

• “This concept covers....”

• “This information is about....”

• “The following chapter explains....”

These constructions take up valuable space without adding any useful information.

Incorrect
Mountain bike wheel comparison
This topic compares 26-inch mountain bike wheels
to 29-inch wheels.

Correct
Mountain bike wheel comparison
Deciding which wheel size to use for your mountain
bike depends on what environments you ride in. The 26-inch
wheel and the 29-inch wheel both have advantages and disad-
vantages depending on where and how you ride.

This issue tracks minor style issues and typos identified in the guide that can be fixed separately from larger updates.

• https://redhat-documentation.github.io/supplementary-style-guide/index.html#appliance-console

  • set-up -> setup (set-up not recommended by IBM SG, we use setup throughouth the SSG)

• https://redhat-documentation.github.io/supplementary-style-guide/index.html#composite-content-view

  • The abbreviation for Composite Content View should probably be "CCV", not "CVV"

Currently, neither the Supplementary Style Guide nor the IBM Style Guide provide recommendations for how to handle sample CLI commands that require root privileges. A de facto standard practice seems to be to include a $ or # at the beginning of the command to indicate the required permission level.

A few questions to consider (I'm sure that there are probably others that I'm not thinking of right of now):

• Is including a $ or # at the beginning of the command to indicate the required permission level always required? If so, is this method obvious enough to all of our users?
• Should we always, sometimes, or never include sudo in the sample command if executing the command requires root privileges?
• If elevated sudo privileges are required to perform tasks in a procedure, should this requirement always be listed in the Prerequisites section?