Code

Opened 7 months ago

Closed 6 months ago

Last modified 6 months ago

#21701 closed Cleanup/optimization (fixed)

improve discoverability of testing documentation

Reported by: cjerdonek Owned by: timo
Component: Documentation Version: 1.6
Severity: Normal Keywords: testing
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

This ticket is to suggest a couple simple high-level improvements to the organization of the testing documentation.

(1) First, the title of the "stub" intro document Testing in Django is too similar to the title of the main testing document Testing Django Applications. If the stub intro page is to have a generic name, the latter should be called something more specific like "Basic Topics in Testing" (to contrast it with the other main testing document called "Advanced Topics in Testing").

(2) Secondly, currently the two substantive testing documents (i.e. the "basic" page and the "advanced" page) don't show up in the table of contents. Only the stub intro page shows up. This makes it harder to find the more meaningful testing pages (because you have to do an extra click and scroll). I think the table of contents should be more like the HTTP section, where the table of contents contains links to both the stub intro page as well as the substantive sub-documents. So it should like something like the following in the table of contents:

  • Testing in Django
    • Basic Testing Topics
    • Advanced Testing Topics

Attachments (0)

Change History (8)

comment:1 Changed 7 months ago by cjerdonek

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Type changed from Uncategorized to Cleanup/optimization

comment:2 Changed 6 months ago by timo

  • Owner changed from nobody to timo
  • Status changed from new to assigned
  • Triage Stage changed from Unreviewed to Accepted

comment:3 Changed 6 months ago by timo

  • Has patch set

This PR addresses both issues. I've also moved about half of topics/overview.txt to a new doc to make it less intimidating as it's probably one of the longest documentation pages we currently have.

comment:4 Changed 6 months ago by cjerdonek

Thanks. From the diff, the change looks like a great improvement.

One suggestion though: you might want to do a global search and replace for the old section title "Testing Django applications." For example, it appears here. There may be other section title references that need to be fixed, too, based on your changes. I'm not 100% sure.

comment:5 Changed 6 months ago by timo

Thanks for the review -- I've updated several titles per your suggestion.

comment:6 Changed 6 months ago by cjerdonek

Looks good, thanks!

comment:7 Changed 6 months ago by Tim Graham <timograham@…>

  • Resolution set to fixed
  • Status changed from assigned to closed

In 9953e98e6ad9298869cd12e20bd3c05c0d19fa10:

Fixed #21701 -- Improved testing doc titles and added testing/tools.txt.

Thanks cjerdonek for the suggestion.

comment:8 Changed 6 months ago by Tim Graham <timograham@…>

In f82eb493015f4fbf0b8fc063f561b5135fc815de:

[1.6.x] Fixed #21701 -- Improved testing doc titles and added testing/tools.txt.

Thanks cjerdonek for the suggestion.

Backport of 9953e98e6a from master

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.