Clarify capitalization for links in the style guide

[giorgionaps]

When we reference a heading verbatim, for example, ## Set up cluster, it’s not clear from the current style guide whether the link text should preserve the exact heading capitalization ([Set up cluster]) or be treated as regular prose ([set up cluster]).

The style guide specifies that:

• Headings use sentence case.
• Section references must always be links.
• We should use descriptive link text.

However, it doesn’t explicitly state whether link text should match the heading text exactly when referencing a section by name. Because of that, both interpretations seem defensible:

• Preserve capitalization because the heading is effectively a named section.
• Lowercase it because link text is part of running prose.

Since both approaches are reasonable under the current wording, I think this is more of a gap in the guide than a stylistic mistake in any specific PR. It would be good to align on one consistent rule so we avoid review churn and inconsistencies going forward.

[alexronquillo]

In my opinion, we should use lowercase when we use a link naturally in content (in general, I also prefer this style of linking):

Learn how to search batch operations.

When we reference another page by its title, we should preserve the sentence-case capitalization:

To learn more, see Search batch operations.

This is supported by Google's style guide, which explicitly prefers sentence case references to titles and headings, even if the page's actual title isn't properly in sentence case:

In references to any title or heading from a document that follows this guide, use sentence case even if the title or heading itself uses title case. That way, when the title or heading is eventually updated to sentence case, the reference will match. (source)

Microsoft's style guide doesn't seem to have an explicit preference.

Since our style guide also references the AP Style Guide, I would also argue this is more in line with the their approach to referencing other works (retain capitalization):

Works: Things such as books, movies, paintings and so on get title-style capitalization and quotation marks: “He couldn’t put down ‘The AP Stylebook'”; “Her favorite album was ‘Love Is Hell.'” (source)

In fact, it could be nice to create a simple mdx component that just pulls the page title and places it in the doc as-is at build time. To continue the example, if a bunch of pages reference "Search batch operations", and the title changes to "Searching batch ops", there's nothing keeping all those other references up-to-date. Different problem, but the solution could be related.

[christinaausley]

I don't typically have super strong opinions on style decisions, but I think I do have strong opinions on this one.

I agree this is a gap in the style guide, not a mistake in individual PRs. To resolve it cleanly and avoid review churn, I propose we standardize on the following rule:

Use sentence-case link text in all running prose, even when linking to a section or page whose heading is being referenced.
Preserve original capitalization only when linking to external, standalone works (books, movies, reports, named publications).

Rationale below:

Link text is prose, not a heading label

Inline links are read as part of the sentence, not as formal section names. Sentence case keeps paragraphs readable and avoids unnecessary capitalization.

• ✔️ Learn how to [set up cluster].
• ❌ Learn how to [Set up cluster].

I think the latter, for lack of better words, just looks wonky. I worry about introducing this in some instances and not others, I think many readers will see it and not fully understand why some are uppercase and some are not, though we are able to discern that as technical writers.

This aligns with industry style guides

• Google developer documentation
  Google explicitly recommends sentence case when referencing titles or headings, even if the source title isn’t in sentence case.
  https://developers.google.com/style/capitalization#capitalization-in-references

• Microsoft Writing Style Guide
  While less explicit, Microsoft documentation consistently uses sentence-case links in running prose and reserves capitalization for headings, navigation, and UI labels.
  https://learn.microsoft.com/en-us/style-guide/capitalization

• AP Style Guide
  AP distinguishes between titles of works (which retain capitalization) and ordinary prose references, supporting sentence case for internal documentation links and preserved capitalization for external works.
  https://www.apstylebook.com/

This matches our existing documentation practice

For many years, we’ve consistently (for the most part) lowercased link text in running prose across the documentation. Reversing this pattern would require a broad audit and cleanup pass, which doesn’t seem like a good use of time right now given higher-priority work. Formalizing the existing convention gives us clarity without introducing unnecessary churn.

Of course, we should detail this in the style guide regardless of the decision here.

[christinaausley]

I did also pull together some industry examples from competitors:

• Temporal
  Uses sentence-case links in paragraphs, regardless of heading capitalization.
  https://docs.temporal.io/

• Apache Airflow
  Treats links as prose rather than verbatim section names.
  https://airflow.apache.org/docs/

• HashiCorp (Terraform, Vault, Nomad)
  Consistently uses sentence-case links in running text, even when page titles are title case.
  https://developer.hashicorp.com/

• AWS
  Favors sentence case for inline links and reserves capitalization for headings, navigation, and UI labels.
  https://docs.aws.amazon.com/