#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 , 11 years ago
Type: | Uncategorized → Cleanup/optimization |
---|
comment:2 by , 11 years ago
Owner: | changed from | to
---|---|
Status: | new → assigned |
Triage Stage: | Unreviewed → Accepted |
comment:3 by , 11 years ago
Has patch: | set |
---|
comment:4 by , 11 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 , 11 years ago
Thanks for the review -- I've updated several titles per your suggestion.
comment:7 by , 11 years ago
Resolution: | → fixed |
---|---|
Status: | assigned → closed |
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.