[Django] #36304: Classes functions (etc) should have a header in the documentation

[Django]

#36304: Classes functions (etc) should have a header in the documentation
-------------------------------------+-------------------------------------
Reporter: Sarah Boyce | Type:
| Cleanup/optimization
Status: new | Component:
| Documentation
Version: 5.2 | Severity: Normal
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Currently, the docs are slightly inconsistent whether classes/functions
have their own header or not.
For example:
- https://docs.djangoproject.com/en/5.2/ref/utils/ lacks headers for many
functions e.g.
https://docs.djangoproject.com/en/5.2/ref/utils/#django.utils.cache.patch_cache_control
- https://docs.djangoproject.com/en/5.2/ref/models/fields/ has generous
headers

Following a conversation on the forum, being generous with headers is
preferable because:
- it improves the table of contents to make it easier to navigate the page
for all users
- the page is more accessible to screen reader users as they can navigate
via headers
- (minor) the djangoproject.com docs search checks the table of contents
when ranking search results (so adding headers improves the search
results)

The discussion is here: https://forum.djangoproject.com/t/set-toc-object-
entries-true-to-auto-add-functions-classes-to-the-pages-table-of-
contents/38902/7

I propose that we add that we should have a "duplicate" header above the
class/function definition to our writing documentation guide:
https://docs.djangoproject.com/en/5.2/internals/contributing/writing-
documentation/#guidelines-for-restructuredtext-files
--
Ticket URL: <https://code.djangoproject.com/ticket/36304>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#36304: Classes functions (etc) should have a header in the documentation

--------------------------------------+------------------------------------
Reporter: Sarah Boyce | Owner: (none)

Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 5.2

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

--------------------------------------+------------------------------------
Changes (by Natalia Bidart):

* stage: Unreviewed => Accepted


Old description:

> Currently, the docs are slightly inconsistent whether classes/functions
> have their own header or not.
> For example:
> - https://docs.djangoproject.com/en/5.2/ref/utils/ lacks headers for many
> functions e.g.
> https://docs.djangoproject.com/en/5.2/ref/utils/#django.utils.cache.patch_cache_control
> - https://docs.djangoproject.com/en/5.2/ref/models/fields/ has generous
> headers
>
> Following a conversation on the forum, being generous with headers is
> preferable because:
> - it improves the table of contents to make it easier to navigate the
> page for all users
> - the page is more accessible to screen reader users as they can navigate
> via headers
> - (minor) the djangoproject.com docs search checks the table of contents
> when ranking search results (so adding headers improves the search
> results)
>
> The discussion is here: https://forum.djangoproject.com/t/set-toc-object-
> entries-true-to-auto-add-functions-classes-to-the-pages-table-of-
> contents/38902/7
>
> I propose that we add that we should have a "duplicate" header above the
> class/function definition to our writing documentation guide:
> https://docs.djangoproject.com/en/5.2/internals/contributing/writing-
> documentation/#guidelines-for-restructuredtext-files

New description:

Currently, the docs are slightly inconsistent whether classes/functions
have their own header or not.
For example:
- https://docs.djangoproject.com/en/5.2/ref/utils/ lacks headers for many
functions e.g.
https://docs.djangoproject.com/en/5.2/ref/utils/#django.utils.cache.patch_cache_control
- https://docs.djangoproject.com/en/5.2/ref/models/fields/ has generous
headers

Following a conversation on the forum, being generous with headers is
preferable because:
- it improves the table of contents to make it easier to navigate the page
for all users
- the page is more accessible to screen reader users as they can navigate
via headers
- (minor) the djangoproject.com docs search checks the table of contents
when ranking search results (so adding headers improves the search
results)

The discussion is here: https://forum.djangoproject.com/t/set-toc-object-
entries-true-to-auto-add-functions-classes-to-the-pages-table-of-
contents/38902/7

I propose we update our documentation guide to include adding a
"duplicate" header above class or function definitions:
https://docs.djangoproject.com/en/5.2/internals/contributing/writing-
documentation/#guidelines-for-restructuredtext-files

--
Comment:

I think this makes sense and it aligns with the conversation in the forum
post.
--
Ticket URL: <https://code.djangoproject.com/ticket/36304#comment:1>

[Django]

#36304: Classes functions (etc) should have a header in the documentation

-------------------------------------+-------------------------------------
Reporter: Sarah Boyce | Owner: Ahmed
Type: | Nassar
Cleanup/optimization | Status: assigned

Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Ahmed Nassar):

* owner: (none) => Ahmed Nassar
* status: new => assigned

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

[Django]

#36304: Classes functions (etc) should have a header in the documentation
-------------------------------------+-------------------------------------
Reporter: Sarah Boyce | Owner: Ahmed
Type: | Nassar
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Ahmed Nassar):

* has_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/36304#comment:3>

[Django]

#36304: Classes functions (etc) should have a header in the documentation
-------------------------------------+-------------------------------------
Reporter: Sarah Boyce | Owner: Ahmed
Type: | Nassar
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 1

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

Changes (by Mariusz Felisiak):

* needs_better_patch: 0 => 1

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

[Django]

#36304: Classes functions (etc) should have a header in the documentation
-------------------------------------+-------------------------------------
Reporter: Sarah Boyce | Owner: Ahmed
Type: | Nassar
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0

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

Changes (by Ahmed Nassar):

* needs_better_patch: 1 => 0

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

[Django]

#36304: Classes functions (etc) should have a header in the documentation
-------------------------------------+-------------------------------------
Reporter: Sarah Boyce | Owner: Ahmed
Type: | Nassar
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 1

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

Changes (by Andrew Northall):

* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/36304#comment:6>

[Django]

#36304: Classes functions (etc) should have a header in the documentation
-------------------------------------+-------------------------------------
Reporter: Sarah Boyce | Owner: Ahmed
Type: | Nassar
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0

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

Changes (by Ahmed Nassar):

* needs_better_patch: 1 => 0

--
Ticket URL: <https://code.djangoproject.com/ticket/36304#comment:7>

[Django]

#36304: Classes functions (etc) should have a header in the documentation
-------------------------------------+-------------------------------------
Reporter: Sarah Boyce | Owner: Ahmed
Type: | Nassar
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 1

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

Changes (by Andrew Northall):

* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/36304#comment:8>