#10092 closed (duplicate)
Reference documentation lowest-level headings too small and lack indents
| Reported by: | adrian_nye | Owned by: | Jacob |
|---|---|---|---|
| Component: | Documentation | Version: | dev |
| Severity: | Keywords: | reference | |
| Cc: | Triage Stage: | Accepted | |
| Has patch: | yes | Needs documentation: | no |
| Needs tests: | no | Patch needs improvement: | yes |
| Easy pickings: | no | UI/UX: | no |
Description (last modified by )
The reference doc is tough to read because the headings for individual functions and methods are the same size as the surrounding text and in a less-contrasting color (green) than the surrounding text. Therefore even though they are "bold" they don't stand out. When "New in Django 1.x" is next to one of these headings, it is bigger than the heading.
In some of the tutorial doc, the descriptive text is indented, and the headings stand out better. For example see "exact" in http://docs.djangoproject.com/en/dev/topics/db/queries/
If this was done in the reference as well it would be better.
Attachments (1)
Change History (9)
comment:1 by , 16 years ago
comment:2 by , 16 years ago
| milestone: | → 1.1 |
|---|---|
| Triage Stage: | Unreviewed → Accepted |
comment:3 by , 16 years ago
| Owner: | changed from to |
|---|---|
| Status: | new → assigned |
by , 16 years ago
| Attachment: | 10092-reference-dt-emphasis-r10680.diff added |
|---|
comment:4 by , 16 years ago
| Has patch: | set |
|---|---|
| Version: | 1.0 → SVN |
I didn't add indent as it seems to go against the "spirit" of an HTML definition list. Made the text slightly larger and added faded border-bottom.
comment:5 by , 16 years ago
| milestone: | 1.1 |
|---|
comment:7 by , 14 years ago
| Description: | modified (diff) |
|---|---|
| Patch needs improvement: | set |
| Resolution: | → duplicate |
| Status: | assigned → closed |
Several notes:
- The indentation problem the OP points to is actually a problem with the indenting in the docs files themselves, not a CSS issue. I've been systematically fixing poorly indented files as I come across them. Any specific cases should be opened as separate tickets. I agree that proper indentation adds a lot to readability, though.
- IMHO, the border-bottom property in the provided patch actually detracts from readability as it's a visual break that interrupts the flow of logically-related sections.
- Increasing the size of the dt tag to 1.3em (or 130%) makes it larger than an h4 tag (125%). At most the two should be equal.
Overall, I think this ticket should be closed in favor of #11930, wherein we can do a complete audit of the heading sizes and make sure that they all have a proper relation to each other (including heading-like items such as dt tags). As such I'm going to close it as a duplicate... Jacob, feel free to reopen if you disagree.
Another option would be to put a 1 pixel border around the function, method, or property name. This would make them stand out better.