cockroachdb / cockroachdb/docs

All links and TOC entries should use exact page titles

Open
#5,850 3 comments 0 reactions 1 assignee Claimed by @shannonbradshaw View on GitHub
P-2 T-incorrect-or-unclear-info
Dominant language
HTML
Stars
212
Forks
476
Avg merge
40m
Merged PRs (30d)
3

Description

Richard Loveland (rmloveland) commented:

Currently, there are instances of TOC entries that don't match the page title they're referring to, and link text that does not match the title of the target page.

This is inconsistent and may lead to confusion. For example, I might be wonder if I am looking at the right page, or if the link is pointing to something I'm interested in.

Here are some concrete examples of mismatches (seen at random, no desire to pick on specific people, I am also "guilty"):

- TOC entries that say 'Tuning Tutorial', but the page title says 'Performance Tuning' (https://www.cockroachlabs.com/docs/v19.2/performance-tuning-insecure.html)

- Link text that says 'SQL Best Practices', but the page is actually entitled 'SQL Performance Best Practices' (https://www.cockroachlabs.com/docs/v19.2/sql-tuning-with-explain.html)

Estimated scope of work:

- Audit all TOC items and ensure that TOC title and YAML title and title displayed on page are the same

- Audit links and ensure that link titles match the titles of the pages they point to (except in obvious cases such as when the link is embedded in prose a la "See [here]() for a thing").

Jira Issue: DOC-367

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.