Opened 6 years ago

Closed 4 years ago

Last modified 4 years ago

#11930 closed (fixed)

Django docs styles confuse H3 & H4

Reported by: david@… Owned by: cogat
Component: *.djangoproject.com Version: 1.1
Severity: Keywords: sprintdec2010
Cc: justinlilly@… Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

The Django docs are confusing because H3 is considerably less prominent than H4.

For example, check out http://docs.djangoproject.com/en/dev/howto/custom-template-tags/, and try to find where it starts talking about writing your own tags (not your own filters).

The H3 is 15px but looks almost the same size as the H4, which is all-caps and black. I think the solution is making h3 a bit stronger, with more margin-top, and the H4 not #000.

Y'all might not notice, since you're already clued in to look for the green. But even after a week navigating these, I still am confused looking through them.

Attachments (4)

djangoproject_css.diff (2.8 KB) - added by cogat 4 years ago.
Typography fixes for h3/h4
Django | Custom template tags and filters | Django documentation-1.jpg (80.1 KB) - added by cogat 4 years ago.
Illustrating impact on H1-3
Django | Custom template tags and filters | Django documentation-2.jpg (96.0 KB) - added by cogat 4 years ago.
Illustrating impact on H4, verdana bold
Django | Custom template tags and filters | Django documentation-3.jpg (97.3 KB) - added by cogat 4 years ago.
Illustrating impact on H3-4

Download all attachments as: .zip

Change History (14)

comment:1 Changed 5 years ago by russellm

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

There is a lot that could be done with the CSS for the docs - indenting, font sizes, margins/padding...

comment:2 Changed 5 years ago by poswald

  • milestone set to 1.3

comment:3 Changed 5 years ago by gabrielhurley

I agree, the CSS for the docs needs a full audit for items such as:

  • Relationship of heading sizes (h1-h6, plus heading-like items such as dt tags)
  • Heading colors (some are green, some are black... how does this affect readability? is the split logical?)
  • Margin/padding (are these applied consistently? do they stack appropriately?)
  • Use of font-weight: bold and font-style: italic (are they consistent and logical?)
  • Proper line-height for various font sizes to preserve "rhythm" of text
  • Cross-browser issues (I've never looked at the docs with IE6, have you? ;-) )
  • Accessibility issues (e.g. are we providing useful styles useful for keyboard navigation, et. al.?)

Indenting is actually a problem with the indentation in the docs files themselves, not related to the CSS (in most cases). I fix these as I find them... specific cases should be their own tickets.

comment:4 Changed 4 years ago by cogat

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

comment:5 Changed 4 years ago by cogat

  • Keywords sprintdec2010 added

I'll embark on an audit of the CSS.

Changed 4 years ago by cogat

Typography fixes for h3/h4

comment:6 Changed 4 years ago by cogat

It seems the core reason for the h3/h4 discrepancy is that h4 has to compete with Verdana bold, which is VERY black. See http://docs.djangoproject.com/en/dev/howto/custom-template-tags/#filters-and-auto-escaping for a typical example.

The patch I just attached reduces the prominence of Verdana bold in documentation, allowing h4 to be brought into alignment with the other headings. The only way of doing this that doesn't look strange is to make the color of <strong> paler.

I have also toned down the appearance of "New in Django 1.x" callouts. Currently they are way too prominent, competing with headings. The information is too ambient/meta for such visual dominance, especially given the version note heading every documentation page.

HOWEVER, the base.css that the patch works against ISN'T in the repository - I had to save it from the site directly. Who is the custodian of this file? (NB the Sphinx theme CSS doesn't have the h3/h4 problem).

I'll attach screenshots of the changes now.

Changed 4 years ago by cogat

Illustrating impact on H1-3

Changed 4 years ago by cogat

Illustrating impact on H4, verdana bold

Changed 4 years ago by cogat

Illustrating impact on H3-4

comment:7 Changed 4 years ago by justinlilly

  • Cc justinlilly@… added
  • Component changed from Documentation to Django Web site
  • Has patch set

comment:8 Changed 4 years ago by jacob

  • Resolution set to fixed
  • Status changed from assigned to closed

Fixed in recent pushes thanks to Justin Lilly.

comment:9 Changed 4 years ago by david@…

Surprised to see that H2 and H3 are still reversed in the image above. Glance at them, imagining you're scanning the document for a header -- which one is more prominent?

It's an easy fix -- just switch the colors. H3 could be the light color that H2 now is. Or just make H2 darker.

If this is how the fix went in, it did not fix the original problem. Other styles seem better.

comment:10 Changed 4 years ago by jacob

  • milestone 1.3 deleted

Milestone 1.3 deleted

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