Code

Opened 5 years ago

Closed 4 years ago

Last modified 3 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 gabrielhurley)

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

Download all attachments as: .zip

Change History (9)

comment:1 Changed 5 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 5 years ago by jacob

  • milestone set to 1.1
  • Triage Stage changed from Unreviewed to Accepted

comment:3 Changed 5 years ago by jacob

  • Owner changed from nobody to jacob
  • Status changed from new to assigned

Changed 5 years ago by idangazit

comment:4 Changed 5 years ago by idangazit

  • Has patch set
  • Version changed from 1.0 to 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 Changed 5 years ago by jacob

  • milestone 1.1 deleted

comment:6 Changed 4 years ago by poswald

  • milestone set to 1.3

Somewhat related to #11930

comment:7 Changed 4 years ago by gabrielhurley

  • Description modified (diff)
  • Patch needs improvement set
  • Resolution set to duplicate
  • Status changed from assigned to closed

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 3 years ago by jacob

  • milestone 1.3 deleted

Milestone 1.3 deleted

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.