Opened 15 years ago

Closed 14 years ago

Last modified 13 years ago

#11930 closed (fixed)

Django docs styles confuse H3 & H4

Reported by: david@… Owned by: Greg Turner
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: no UI/UX: no

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 Greg Turner 14 years ago.
Typography fixes for h3/h4
Django | Custom template tags and filters | Django documentation-1.jpg (80.1 KB ) - added by Greg Turner 14 years ago.
Illustrating impact on H1-3
Django | Custom template tags and filters | Django documentation-2.jpg (96.0 KB ) - added by Greg Turner 14 years ago.
Illustrating impact on H4, verdana bold
Django | Custom template tags and filters | Django documentation-3.jpg (97.3 KB ) - added by Greg Turner 14 years ago.
Illustrating impact on H3-4

Download all attachments as: .zip

Change History (14)

comment:1 by Russell Keith-Magee, 15 years ago

Triage Stage: UnreviewedAccepted

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

comment:2 by Paul Oswald, 14 years ago

milestone: 1.3

comment:3 by Gabriel Hurley, 14 years ago

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 by Greg Turner, 14 years ago

Owner: changed from nobody to Greg Turner
Status: newassigned

comment:5 by Greg Turner, 14 years ago

Keywords: sprintdec2010 added

I'll embark on an audit of the CSS.

by Greg Turner, 14 years ago

Attachment: djangoproject_css.diff added

Typography fixes for h3/h4

comment:6 by Greg Turner, 14 years ago

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.

by Greg Turner, 14 years ago

Illustrating impact on H1-3

by Greg Turner, 14 years ago

Illustrating impact on H4, verdana bold

by Greg Turner, 14 years ago

Illustrating impact on H3-4

comment:7 by Justin Lilly, 14 years ago

Cc: justinlilly@… added
Component: DocumentationDjango Web site
Has patch: set

comment:8 by Jacob, 14 years ago

Resolution: fixed
Status: assignedclosed

Fixed in recent pushes thanks to Justin Lilly.

comment:9 by david@…, 14 years ago

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

milestone: 1.3

Milestone 1.3 deleted

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