Django docs styles confuse H3 & H4

[david@…]

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.

[Russell Keith-Magee]

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

[Gabriel Hurley]

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.

[Greg Turner]

I'll embark on an audit of the CSS.

[Greg Turner]

Typography fixes for h3/h4

[Greg Turner]

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.

[Greg Turner]

Illustrating impact on H1-3

[Greg Turner]

Illustrating impact on H4, verdana bold

[Greg Turner]

Illustrating impact on H3-4

[Justin Lilly]

​https://github.com/jacobian/djangoproject.com/pull/11

[Jacob]

Fixed in recent pushes thanks to Justin Lilly.

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

[Jacob]

Milestone 1.3 deleted