diff --git a/contributing_to_docs/doc_guidelines.adoc b/contributing_to_docs/doc_guidelines.adoc index 5ae97383ec8b..9387f895edc0 100644 --- a/contributing_to_docs/doc_guidelines.adoc +++ b/contributing_to_docs/doc_guidelines.adoc @@ -949,6 +949,17 @@ IMPORTANT: You cannot link to a repository that is hosted on www.github.com. An TIP: If you want to build a link from a URL _without_ changing the text from the actual URL, just print the URL without adding a `[friendly text]` block at the end; it will automatically be rendered as a link. +==== Guidance for including outside sources +In general, avoid linking to sources outside of an official Red Hat domain whenever possible. + +Some acceptable exceptions to this rule include: + +1. Links to third-party product documentation when it would be otherwise unreasonable or impossible to write procedures using another product. +2. Upstream resources for a feature or component based on an upstream project when re-writing the resource for downstream use would be too arduous to write for too little value, or too difficult to maintain. +3. Upstream API references + +If you feel you need to link to an outside source, discuss it with a content strategist, and then make sure you have approval from your PM and engineering stakeholders and the Product Operations team member who works in your area. + === Links to internal content There are two scenarios for linking to other assemblies: