Opened 8 years ago

Closed 6 years ago

Last modified 5 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: master
Severity: Keywords: reference
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: UI/UX:

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 7 years ago.

Download all attachments as: .zip

Change History (9)

comment:1 Changed 8 years ago by anonymous

Needs documentation: unset
Needs tests: unset
Patch needs improvement: unset

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 Changed 8 years ago by Jacob

milestone: 1.1
Triage Stage: UnreviewedAccepted

comment:3 Changed 7 years ago by Jacob

Owner: changed from nobody to Jacob
Status: newassigned

Changed 7 years ago by Idan Gazit

comment:4 Changed 7 years ago by Idan Gazit

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 Changed 7 years ago by Jacob

milestone: 1.1

comment:6 Changed 6 years ago by Paul Oswald

milestone: 1.3

Somewhat related to #11930

comment:7 Changed 6 years ago by Gabriel Hurley

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 Changed 5 years ago by Jacob

milestone: 1.3

Milestone 1.3 deleted

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