[Django] #35863: Advice for new contributors documentation should be structured with headings - Accessibility

[Django]

#35863: Advice for new contributors documentation should be structured with
headings - Accessibility
-------------------------------------+-------------------------------------
Reporter: Sarah Sanger | Type:
| Cleanup/optimization
Status: new | Component:
| Documentation
Version: 5.1 | Severity: Normal
Keywords: Accessibility | Triage Stage:
Documentation Contributing | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 1
-------------------------------------+-------------------------------------
The [https://docs.djangoproject.com/en/5.1/internals/contributing/new-
contributors/ advice for new contributors] documentation page is misusing
bold text within list items as headings. This is a common accessibility
issue. Though visually the text stands out, for screen reader users all of
those guidelines are one big unstructured list. They will get no
indication of what’s a heading and what’s the guideline’s contents.


For all users, it would also be very neat to be able to link straight to
one of those guidelines. So – we need to replace the bold text with
semantic headings (heading level 3)
--
Ticket URL: <https://code.djangoproject.com/ticket/35863>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#35863: Advice for new contributors documentation should be structured with
headings - Accessibility
-------------------------------------+-------------------------------------

Reporter: Sarah Sanger | Owner: Sarah
Type: | Sanger
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.1
Severity: Normal | Resolution:

Keywords: Accessibility | Triage Stage:
Documentation Contributing | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 1
-------------------------------------+-------------------------------------

Changes (by Sarah Sanger):

* owner: (none) => Sarah Sanger
* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/35863#comment:1>

[Django]

#35863: Advice for new contributors documentation should be structured with
headings - Accessibility
-------------------------------------+-------------------------------------

Reporter: Sarah Sanger | Owner: (none)
Type: | Status: assigned
Cleanup/optimization |

Component: Documentation | Version: 5.1
Severity: Normal | Resolution:
Keywords: Accessibility | Triage Stage:
Documentation Contributing | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 1
-------------------------------------+-------------------------------------
Changes (by Sarah Sanger):

* owner: Sarah Sanger => (none)

--
Ticket URL: <https://code.djangoproject.com/ticket/35863#comment:2>

[Django]

#35863: Advice for new contributors documentation should be structured with
headings - Accessibility
-------------------------------------+-------------------------------------

Reporter: Sarah Sanger | Owner: Sarah
Type: | Sanger
Cleanup/optimization | Status: assigned

Component: Documentation | Version: 5.1
Severity: Normal | Resolution:

Keywords: Accessibility | Triage Stage: Accepted
Documentation Contributing |

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Thibaud Colas):

* cc: Thibaud Colas (added)

* owner: (none) => Sarah Sanger

* stage: Unreviewed => Accepted
* ui_ux: 1 => 0

Comment:

Thank you for the report Sarah! The current pattern is a pretty clear
failure of [https://www.w3.org/WAI/WCAG22/Understanding/info-and-
relationships.html WCAG SC 1.3.1 Info and Relationships]:

> Information, structure, and relationships conveyed through presentation
can be programmatically determined or are available in text.

For reference, we also did a similar change in
[https://github.com/django/django/pull/17549 PR #17549]. Note for the page
you mention there seems to be two lists with this issue; under First steps
and Guidelines.
--
Ticket URL: <https://code.djangoproject.com/ticket/35863#comment:3>

[Django]

#35863: Advice for new contributors documentation should be structured with
headings - Accessibility
-------------------------------------+-------------------------------------
Reporter: Sarah Sanger | Owner: Sarah
Type: | Sanger
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.1
Severity: Normal | Resolution:
Keywords: Accessibility | Triage Stage: Accepted
Documentation Contributing |

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce):

* has_patch: 0 => 1
* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/35863#comment:4>

[Django]

#35863: Advice for new contributors documentation should be structured with
headings - Accessibility
-------------------------------------+-------------------------------------
Reporter: Sarah Sanger | Owner: Sarah
Type: | Sanger
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.1
Severity: Normal | Resolution:

Keywords: Accessibility | Triage Stage: Ready for
Documentation Contributing | checkin

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Sarah Boyce):

* needs_better_patch: 1 => 0
* stage: Accepted => Ready for checkin

--
Ticket URL: <https://code.djangoproject.com/ticket/35863#comment:5>

[Django]

#35863: Advice for new contributors documentation should be structured with
headings - Accessibility
-------------------------------------+-------------------------------------
Reporter: Sarah Sanger | Owner: Sarah
Type: | Sanger

Cleanup/optimization | Status: closed
Component: Documentation | Version: 5.1
Severity: Normal | Resolution: fixed

Keywords: Accessibility | Triage Stage: Ready for
Documentation Contributing | checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce <42296566+sarahboyce@…>):

* resolution: => fixed
* status: assigned => closed

Comment:

In [changeset:"c4c076223eb73553d3bc8fbc11be2c529d9aea6b" c4c07622]:
{{{#!CommitTicketReference repository=""
revision="c4c076223eb73553d3bc8fbc11be2c529d9aea6b"
Fixed #35863 -- Replaced bold text with heading level 3 in new
contributors docs.

This improves accessibility for screen reader users, see WCAG SC 1.3.1
Info and Relationships:
https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/35863#comment:6>

[Django]

#35863: Advice for new contributors documentation should be structured with
headings - Accessibility
-------------------------------------+-------------------------------------
Reporter: Sarah Sanger | Owner: Sarah
Type: | Sanger
Cleanup/optimization | Status: closed
Component: Documentation | Version: 5.1
Severity: Normal | Resolution: fixed
Keywords: Accessibility | Triage Stage: Ready for
Documentation Contributing | checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Sarah Boyce <42296566+sarahboyce@…>):

In [changeset:"08c0c421394048a0f4c367bc1798ee5d332c5b62" 08c0c421]:
{{{#!CommitTicketReference repository=""
revision="08c0c421394048a0f4c367bc1798ee5d332c5b62"
[5.1.x] Fixed #35863 -- Replaced bold text with heading level 3 in new

contributors docs.

This improves accessibility for screen reader users, see WCAG SC 1.3.1
Info and Relationships:
https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html

Backport of c4c076223eb73553d3bc8fbc11be2c529d9aea6b from main.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/35863#comment:7>