more-info-xref-guideline: Updating the doc_guidelines.adoc with for m…

[dfitzmau]

INTERNAL FIX.

Add guidance for the "lead-in link sentence" style as per Slack thread.

Preivew link: Lead-in link sentences

[ocpdocs-previewbot]

🤖 Mon Apr 15 16:01:37 - Prow CI generated the docs preview:

https://73514--ocpdocs-pr.netlify.app/

[dfitzmau]

/label peer-review-needed

[dfitzmau]

@skrthomas . Thanks for the comments.

The primary aim of these guidelines is to advise a consistent style as the purpose of this PR stemmed from a new writer finding numerous variants on a "See x in y" style reference. Leaving the gate open and not providing clear guidance could make my PR's purpose invalid. I would like to provide as much information as possible, so any confusion from checking existing published docs is squashed.

[dfitzmau]

RE: I confirm that the contributing guidelines advise to only put text in the xref bracket, not necessarily an entire sentence, just the title of the section you're linking to: https://github.com/openshift/openshift-docs/blob/main/contributing_to_docs/doc_guidelines.adoc#additional-resources-sections

Correct in that our current guidelines state this, but what if something more granular exists in a module and the xref'd title does not match up with the indended reference pointer? Should we use a full sentence here? Perhaps the "xref" guideline as it stands now is too restrictive?

[dfitzmau]

Hi @bergerhoffer , @jeana-redhat , and @skrthomas . Do you think we need to state "For more information" in the following sentence?

Use the following format when pointing to a section in the same document: For more information, see "<section_name>."

Would the module or assembly title be enough?

Example:

[dfitzmau]

I added the following section based on the style I see for KBase article in the RH SSG:

When pointing to a link that exists external to Red Hat's customer portal documentation, use the link attribute, place the link in an Additional resources section, and use the <document_heading_name> (<document_source>) format. For example, see link:https://aws.amazon.com/about-aws/global-infrastructure/localzones/features/[AWS Local Zones features] (AWS documentation).

I'm confused why my preview link is not updating as the source file should have my latest changes :cry:. Very strange as the latest HTML file metadata matches my latest push to my local server storage space:

[dfitzmau]

Hi @bergerhoffer , @jeana-redhat , and @skrthomas . What do you think of the latest changes? Will I send this PR for peer review?

[jeana-redhat]

Hi @bergerhoffer , @jeana-redhat , and @skrthomas . Do you think we need to state "For more information" in the following sentence?

Use the following format when pointing to a section in the same document: For more information, see "<section_name>."

Would the module or assembly title be enough?

Example:

Hey sorry missed this earlier. I'm not 100% certain what you're asking. Do you mean put "for more info" as part of the text with the bullet? If so, no, that bullet should only have a link with the title as the text.

[jeana-redhat]

Hi @bergerhoffer , @jeana-redhat , and @skrthomas . What do you think of the latest changes? Will I send this PR for peer review?

I vote yes to peer review :) Nice work!

[dfitzmau]

/retest

[dfitzmau]

/label peer-review-needed

[adellape]

Was this meant to be peer-review-needed or merge-review-needed?

[dfitzmau]

/label merge-review-needed

[adellape]

@dfitzmau I'm gonna keep merge-review-in-progress label added but hold merge for your thoughts on my latest comments.

[dfitzmau]

/jira-refresh

[dfitzmau]

/retest

[openshift-ci[bot]]

@dfitzmau: all tests passed!

Full PR test history. Your PR dashboard.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. I understand the commands that are listed here.