Opened 15 years ago

Closed 13 years ago

Last modified 12 years ago

#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 Gabriel Hurley)

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)

10092-reference-dt-emphasis-r10680.diff (644 bytes ) - added by Idan Gazit 15 years ago.

Download all attachments as: .zip

Change History (9)

comment:1 by anonymous, 15 years ago

Another option would be to put a 1 pixel border around the function, method, or property name. This would make them stand out better.

comment:2 by Jacob, 15 years ago

milestone: 1.1
Triage Stage: UnreviewedAccepted

comment:3 by Jacob, 15 years ago

Owner: changed from nobody to Jacob
Status: newassigned

by Idan Gazit, 15 years ago

comment:4 by Idan Gazit, 15 years ago

Has patch: set
Version: 1.0SVN

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 Jacob, 15 years ago

milestone: 1.1

comment:6 by Paul Oswald, 13 years ago

milestone: 1.3

Somewhat related to #11930

comment:7 by Gabriel Hurley, 13 years ago

Description: modified (diff)
Patch needs improvement: set
Resolution: duplicate
Status: assignedclosed

Several notes:

  1. 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.
  1. 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.
  1. 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.

comment:8 by Jacob, 12 years ago

milestone: 1.3

Milestone 1.3 deleted

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