search

openshift / openshift-docs

OpenShift 3 and 4 product and community documentation
https://docs.openshift.com
Apache License 2.0
739 stars 1.7k forks source link

Update xref guidelines #53958

Open maxwelldb opened 1 year ago

maxwelldb commented 1 year ago

While working on https://issues.redhat.com/browse/OCPBUGS-4982, I realized that the xref guidelines in this repo are incorrect.

Ex: assemblies in the same directory are not linked to as demonstrated.

The xref guidelines should be fixed and verified.

openshift-bot commented 1 year ago

Issues go stale after 90d of inactivity.

Mark the issue as fresh by commenting /remove-lifecycle stale. Stale issues rot after an additional 30d of inactivity and eventually close. Exclude this issue from closing by commenting /lifecycle frozen.

If this issue is safe to close now please do so with /close.

/lifecycle stale

maxwelldb commented 1 year ago

/remove-lifecycle rotten

openshift-bot commented 1 year ago

Stale issues rot after 30d of inactivity.

Mark the issue as fresh by commenting /remove-lifecycle rotten. Rotten issues close after an additional 30d of inactivity. Exclude this issue from closing by commenting /lifecycle frozen.

If this issue is safe to close now please do so with /close.

/lifecycle rotten /remove-lifecycle stale

rolfedh commented 10 months ago

Thanks for reporting this issue, @maxwelldb. Could you provide a reference to the "xref guidelines in this repo"? I'm evaluating issues for hacktoberfest and this information would help.

maxwelldb commented 10 months ago

image Pulling from my Slack history, as it's been a while:

The example here should actually start xref:../baz/zag...

@rolfedh

rolfedh commented 10 months ago

Thanks, Max! You didn't have to do that! I need help finding the document you made a screenshot of. Can you give me a link?

maxwelldb commented 10 months ago

Oh! Yep. :)

Screenshot of error is from: https://github.com/openshift/openshift-docs/blob/main/contributing_to_docs/doc_guidelines.adoc#links-to-internal-content

bergerhoffer commented 9 months ago

@bobfuru :wave: can you comment on this issue so that we can assign it to you?

bergerhoffer commented 9 months ago

@maxwelldb should these sections actually be combined? Afaik there isn't any difference in how an xref is contructed depending on whether the assembly is in the same directory or not.

If that's true, then it seems like we should get rid of "two scenarios" deal and just cut it down to here's how you xref.

maxwelldb commented 9 months ago

Sounds copacetic.

bobfuru commented 9 months ago

Hi @bergerhoffer! 👋 Please assign this to me. Many thanks!

bergerhoffer commented 9 months ago

@bobfuru Let me know if you'd be up for adjusting the xref guidelines like I recommended above. There really is no difference in the xref guidance depending on where you are linking to.

rolfedh commented 9 months ago

Hi @bergerhoffer. I was out on Friday. It looks like you've got this one.

bobfuru commented 9 months ago

@bobfuru Let me know if you'd be up for adjusting the xref guidelines like I recommended above. There really is no difference in the xref guidance depending on where you are linking to.

Sure, added a change to the PR. Let me know what you think.