Update 3.12 Citing Other Works

[rclee33]

3.12 Citing Other Works seems out of date with our current practices (we do not use footnotes for long URLs), and will be out of alignment with the pending update to the References style (to be documented in Confluence). Because the Style Guide is a commonly used resource for agentic AI workflows, we should align the guidance in both sources.

One option could be to add some frame text to section 3.12 about referring to in-house styles for citation and recommended practices for the intended format. Then following that, perhaps the Style Guide could provide some generic guidance.

For example:

3.12 Citing Other Works

When referencing other publications, consult with internal guidance for the appropriate citation of sources, such as selecting the sources that are appropriate to list, identifying the citation style to use for references, and following recommended practices for the intended deliverable.

General guidelines

• When citing references from external sources, ensure that the content is authoritative, credible, and publicly accessible.
• When referencing internet sites, use meaningful link text for embedded URLs:

Example: "Go here for more information", where "here" is a link.
Improvement: For more information, refer to Red Hat Partner Connect.

[daobrien]

Be careful not to assume that what we do in PTL dictates what should exist in the RHSG.

Sometimes we have to make allowances because our training material requires specific styles, designs, patterns, or whatever, but overall the style guide is for technical writing and is a public guide aimed at a fairly wide audience. (I don't have any numbers on who uses it.) The SG itself still uses footnotes in some places afaik. I don't know if product docs still uses them or not, and there's really no reason to not use them if they "fit". It's true they don't fit in our training content, but that doesn't mean you can't use them in other content.