Update external link guidelines?

[apinnick]

supplementary_style_guide/style_guidelines/links.adoc

Avoid unnecessary links to external sites not owned and operated by Red Hat or IBM.
Links to external sites can change or be unreliable.
In addition, customers might infer that Red Hat endorses or supports the linked content, even if that is not the intent.

I think it would be a good idea to update this guideline. Many of our products are deployed on public cloud platforms like AWS, Azure, or GCP. If we do not link to external sites, we will end up writing documentation that we cannot support or maintain.

Perhaps we could distinguish between sites officially supported by partners and other external sites. Maybe we could even add a disclaimer somewhere in the legal notice that our links do not imply support and that, while we make every effort to keep our documentation up to date, we are not responsible for broken links.

[swopebe]

I will agree, here.

We work on a product similar. Kubernetes products need to doc processes for how to use *.ks and we (RHACM) already point to things like AWS doc for credentials and such.

We aren't copying the text because that is a maintenance issue. Because we are embedded with dev and qe, these links are verified. We have done this since inception of this product at IBM.

IBM style guide a while ago had good guidance, but that seems to be missing now. I like the guidance that Google gives:

https://developers.google.com/style/links-external
I have also attached images from my print (2015) IBM Style manual, though like I said, this is not in the digital manual that I can find.

[apinnick]

@swopebe
Thanks for the Google developers link! Their guidelines make a lot of sense.

[mportman12]

Discussed at the June Style Council meeting. Outcome: Not necessarily an allowlist of trusted partners, but just calling out some examples. So that people know that they might not necessarily need to avoid linking to trusted sites like partner sites, etc. as much as avoiding other less trusted sites.
Need a volunteer to make a PR for this.