Investigate whether "CAUTION" admonition type is now supported

[bergerhoffer]

In our admonitions section [1], we list the supported types of admonitions: NOTE, IMPORTANT, WARNING, and TIP.

We specifically have a note that says that CAUTION isn't supported by the portal and not to use it. However, I just checked where someone did use it [2], and it looks to be fine now. Maybe the issue around the CAUTION type has been resolved with one of the recent portal updates.

@cfbryan Do you know whether CAUTION admonition type is now supported on the portal?

If it is now supported by the portal, we should then decide whether it's something we want to recommend using or not. I personally don't see much of a difference between when you'd want to use WARNING vs CAUTION. But it's not something I feel strongly about.

[1] https://redhat-documentation.github.io/supplementary-style-guide/#admonitions
[2] https://access.redhat.com/documentation/en-us/openshift_container_platform/4.11/html/cicd/pipelines#managing-nonversioned-and-versioned-cluster-tasks

[sbmetz]

CAUTION (and DANGER) indicate potentially hazardous to humans, where Warning is potential data or system loss. It's too soon for me to be certain, but I can imagine that caution/danger could be needed for the Automotive docs.

[sbmetz]

FTR, looks like danger is not in plain asciidoc, but caution is. https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/

[sbmetz]

@bergerhoffer -- I know you've got some separate (internal channels) queries for clarification -- any traction yet?

[bergerhoffer]

@sbmetz No update yet - I've asked in one of the CCS tickets related to admonitions, https://issues.redhat.com/browse/CCS-6063, still waiting on a reply. @IngridT1 can you take a look at the question in this ticket and let us know your thoughts on the CAUTION admonition type (whether we should now allow it if the portal supports it, or if we should continue disallowing it)

[mportman12]

Style Council meeting outcome: @sbmetz will discuss with RHIVOS to see if this admonition would be useful to them.

[dfitzmau]

Hi @sbmetz . Just checking in with you on the status of this admonition based on the previous comment. Issue remains in discussion with RHIVOS?

[Srivaralakshmi]

Hi, @sbmetz. Just checking in with you on the status of this admonition based on the previous comment. Does the issue remain in discussion with RHIVOS?

[sbmetz]

This topic has definitely spurred discussion. We're taking it to RHIVOS council and I'll bring it back to the SSG meetings with key points.

[mportman12]

Discussed at March Style Council meeting. Outcomes were for @sbmetz to reach out to legal to see their thoughts on an admonition for bodily harm. Leave the SSG statement as is for now, until we hear back from legal or more from automotive. Consider the colors - if CAUTION would be bodily harm, seems like it should be red instead of orange.

[mportman12]

@sbmetz any updates on this?

[bredamc]

@sbmetz Any update from legal or RHIVOS about usage of the CAUTION admonition?

[mportman12]

@sbmetz Any updates on this?

[bburt-rh]

@sbmetz Where does this issue stand? Any updates?

[dfitzmau]

Asciidoc have good descriptions of admonition types: https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/

IMO: I would find CAUTION a useful admonition in situations where we cannot say "recommend", but instead orient the product user to take care when configuring certain product capabilities or environments. The CAUTION admonition, IMO, is not ask frightening as WARNING or as limiting, but still places the onus on a product user to really stop and think before they go about configuring a certain environment as it might impact their desired goal.

[mportman12]

@sbmetz Any updates on this?

[mportman12]

@sbmetz Any updates on this?

[sbmetz]

I logged it in a sheet with other Automotive Qs someone was going to be sharing with Legal, and that just came up again this week (no answers yet). I'll follow up on that thread. (I'm not sure how I missed all the call-outs in the issue -- I'll have to refine my email filters!)

[Srivaralakshmi]

@sbmetz Any updates on this?

[sbmetz]

I'll follow up. Thanks for the nudge.

[bburt-rh]

I'll follow up. Thanks for the nudge.

@sbmetz Any progress on this one yet?

[bredamc]

@sbmetz Did you "reach out to legal to see their thoughts on an admonition for bodily harm" yet?
If we need both CAUTION (potentially hazardous to people) and DANGER (potentially lethal or extremely hazardous to people) labels, should we use specific colours for these notices?

[Srivaralakshmi]

@sbmetz Where does this issue stand? Any updates?