Update link guidance to reflect current advice

[jdbaldry]

• Restructured links and references page
• Rewrote relref shortcode destination section
• Fixed linting errors
• Update linking advice

[imatwawana]

Thank you for doing this! I'm not sure what the reasoning is for "discouraging" the use of something vs just saying "do this (other thing)." This is a document that people need to be able to digest super quickly to be effective, and IMO using words like that in this context (vs in a style guideline) isn't helpful, so I've suggested removing all the relref content. If we reverse our decisions on this at some point, that content will live on in the previous versions of this PR, but having it in the WT is just confusing. We need to just say what we want folks to do and tell them how to do it.

[github-actions]

Overall readability score: 60.61 (🟢 +0.57)

File	Readability
_index.md	55.11 (🟢 +0.3)
index.md	62.75 (🟢 +0.61)
index.md	75.34 (-)
index.md	68.88 (🟢 +0.15)
index.md	64.56 (🟢 +0.79)
index.md	61.77 (🟢 +0.3)

View detailed metrics

🟢 - Shows an increase in readability
🔴 - Shows a decrease in readability

File	Readability	FRE	GF	ARI	CLI	DCRS
_index.md	55.11	37.26	7.32	13.9	14.58	7.6
	🟢 +0.3	🟢 +0	🟢 +0.04	🟢 +0.3	🔴 -0.12	🔴 -0.01
index.md	62.75	47.28	8.73	12	12.47	6.77
	🟢 +0.61	🟢 +0.1	🟢 +0.07	🟢 +0.2	🟢 +0.11	🟢 +0.01
index.md	75.34	53.07	6.86	8.8	10.82	6.32
	-	-	-	-	-	-
index.md	68.88	52.05	7.44	10.3	11.87	6.83
	🟢 +0.15	🔴 -0.1	🔴 -0.02	🟢 +0.1	🟢 +0.06	🔴 -0.01
index.md	64.56	47.18	8.64	11.9	12.35	6.35
	🟢 +0.79	🟢 +0.3	🟢 +0.3	🟢 +0	🔴 -0.11	🟢 +0.12
index.md	61.77	49.41	9.29	11.3	12.64	7.13
	🟢 +0.3	🟢 +0.2	🟢 +0.1	🟢 +0.1	🔴 -0.06	🟢 +0.01

Averages:

	Readability	FRE	GF	ARI	CLI	DCRS
Average	60.61	47.52	9.59	11.66	12.08	7.31
	🟢 +0.57	🟢 +0.32	🟢 +0.07	🟢 +0.14	🟢 +0.08	🟢 +0.02

View metric targets

Metric	Range	Ideal score
Flesch Reading Ease	100 (very easy read) to 0 (extremely difficult read)	60
Gunning Fog	6 (very easy read) to 17 (extremely difficult read)	8 or less
Auto. Read. Index	6 (very easy read) to 14 (extremely difficult read)	8 or less
Coleman Liau Index	6 (very easy read) to 17 (extremely difficult read)	8 or less
Dale-Chall Readability	4.9 (very easy read) to 9.9 (extremely difficult read)	6.9 or less

[imatwawana]

I've made some suggestions to hopefully improve clarity and the ability to scan the Links page. Also added a suggestion for the relref section on the Shortcodes page.

[Eve832]

lgtm!

[imatwawana]

I added something in the anchor section that I think I was struggling to explain yesterday. Other than that, just a few minor wording and structure things. But I think one more pass will do it!

[clayton-cornell]

@jdbaldry I'm finding some patterns that aren't explicitly included in the docs here or in what's already published... and maybe it's worth mentioning or clarifying?

Assume a file at: /docs/sources/agent/static/example.md, then:

{{% docs/reference %}}
[example]:  "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/example"
{{% docs/reference %}}

will end in a 404 error when the docs are built....

but this works:

{{% docs/reference %}}
[example]:  "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/example.md"
{{% docs/reference %}}

But this doesn't carry over to _index.md files

{{% docs/reference %}}
[link]:  "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/_index.md"
{{% docs/reference %}}

will resolve fine as will

{{% docs/reference %}}
[link]:  "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow"
{{% docs/reference %}}

[jdbaldry]

The docs/reference shortcode uses the Hugo relref function under the hood and my understanding is that both of your examples should work the same.

For example, linking to errata.md, in https://github.com/grafana/writers-toolkit/blob/jdb%2F2023-10-update-linking-guidance/docs/sources/review/doc-validator/_index.md?plain=1#L28

[osg-grafana]

Suggested change

	1. Convert to lower case.
	1. Convert the header to lower case.

[osg-grafana]

Unblocking with feedback

[jdbaldry]

I'm going to get this merged and we can iterate from there. I am keen to get correct information in our documentation first and we can always polish it later.