Opened 10 years ago

Closed 10 years ago

Last modified 10 years ago

#21701 closed Cleanup/optimization (fixed)

improve discoverability of testing documentation

Reported by: Chris Jerdonek Owned by: Tim Graham
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

Change History (8)

comment:1 by Chris Jerdonek, 10 years ago

Type: UncategorizedCleanup/optimization

comment:2 by Tim Graham, 10 years ago

Owner: changed from nobody to Tim Graham
Status: newassigned
Triage Stage: UnreviewedAccepted

comment:3 by Tim Graham, 10 years ago

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 by Chris Jerdonek, 10 years ago

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 by Tim Graham, 10 years ago

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

comment:6 by Chris Jerdonek, 10 years ago

Looks good, thanks!

comment:7 by Tim Graham <timograham@…>, 10 years ago

Resolution: fixed
Status: assignedclosed

In 9953e98e6ad9298869cd12e20bd3c05c0d19fa10:

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

Thanks cjerdonek for the suggestion.

comment:8 by Tim Graham <timograham@…>, 10 years ago

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

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