Opened 3 weeks ago

Closed 2 weeks ago

Last modified 2 weeks ago

#37409 closed Cleanup/optimization (fixed)

Ambiguous "Overview" link text on the documentation home page

Reported by: Natalia Bidart Owned by: Natalia Bidart
Component: Documentation Version: 6.1
Severity: Normal Keywords: accessibility
Cc: Mike Edmunds, Daniele Procida Triage Stage: Ready for checkin
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

The ​documentation home page uses Overview as the link text 15 times. It is the only duplicated link text on the page. A sighted reader sees which group each one belongs to; someone navigating by a list of links gets 15 identical entries. Most of this is self-inflicted. Every one of those targets already has a distinct title, which docs/index.txt overrides with the generic word.

For most of them the fix is to remove the explicit title and let :doc: use the document's own. Where that would repeat the group label, a short descriptive title does the job. While fixing the link text, a few groups are worth tidying: single-link groups whose label repeats their only link, and About this documentation, which is already reachable under Contributing to Django.

This is a derived from this ​forum post, following ticket #37051.

Change History (6)

comment:1 by David Smith, 3 weeks ago

Triage Stage: Unreviewed → Accepted

comment:2 by Natalia Bidart, 3 weeks ago

Cc: Mike Edmunds Daniele Procida added

comment:3 by Mike Edmunds, 2 weeks ago

Triage Stage: Accepted → Ready for checkin

comment:4 by nessita <124304+nessita@…>, 2 weeks ago

Resolution: → fixed
Status: assigned → closed

In 0357fd1:

Fixed #37409 -- Removed ambiguous "Overview" link text from the docs home page.

The docs home page used "Overview" as the link text 15 times, the only
duplicated link text on that page. A reader navigating by a list of
links got identical entries with no indication of which section each
belonged to. A sixteenth "Overview" comes from the main site's navbar
and is outside this repository.

Every one of those targets already has a distinct title of its own,
which docs/index.txt was overriding with the generic word. Most of
them now use it, via :doc: without an explicit title. Three would have
repeated their group label, and are given a short unique title instead.

Also retitled five of those documents so that the home page can use their
own titles: two to sentence case, matching the rest, and three to drop a
redundant "in Django" suffix.

comment:5 by nessita <124304+nessita@…>, 2 weeks ago

In c8906fe1:

Refs #37409 -- Regrouped single-link entries on the docs home page.

Several entries on the docs home page were a bold label followed by a
single link repeating it. Each now sits where it belongs: "Applications"
with "Settings", both configuration; "Third-party distributions" with
"Installation", both about obtaining Django; and "Design philosophies"
with the release process and security policies, all statements about the
project. The "About this documentation" entry is dropped, since it
pointed at a contributor how-to already reachable under
"Contributing to Django".

comment:6 by nessita <124304+nessita@…>, 2 weeks ago

In 1087f12f:

Refs #37409 -- Corrected docs home links whose text did not match their target.

"Form API" pointed at a page titled "The Forms API". In the i18n group,
"Internationalization" pointed at a page titled "Translation" and
"Localization" linked halfway into that same page, so two consecutive
entries led to one document under two names.

Each entry now uses its page's own title. "Unicode data" moves to that
group from "Content", where it was less at home, and the FAQ's link to
it is corrected in the same way.

Note: See TracTickets for help on using tickets.
Back to Top