Opened 5 years ago

Closed 5 years ago

#17089 closed Cleanup/optimization (wontfix)

Color of fonts used in code

Reported by: colonelcoleslaw@… Owned by: nobody
Component: Documentation Version: 1.3
Severity: Normal Keywords:
Cc: Triage Stage: Someday/Maybe
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: yes

Description

I've appreciated the thorough documentation, but can barely read much of the code samples on the light-green background. It's really bad.

Attachments (3)

code_original.png (146.4 KB) - added by Idan Gazit 5 years ago.
Documentation with the existing code block coloring
code_grey.png (142.3 KB) - added by Idan Gazit 5 years ago.
Documentation with a monochrome code block background
contrasty_text.png (68.3 KB) - added by shaunkelly 5 years ago.

Download all attachments as: .zip

Change History (11)

comment:1 Changed 5 years ago by Aymeric Augustin

Component: UncategorizedDjangoproject.com Web site
Triage Stage: UnreviewedDesign decision needed
Type: UncategorizedCleanup/optimization
UI/UX: set

I'll defer to someone who feels qualified to decide if the contrast is indeed too low.

Last edited 5 years ago by Aymeric Augustin (previous) (diff)

Changed 5 years ago by Idan Gazit

Attachment: code_original.png added

Documentation with the existing code block coloring

Changed 5 years ago by Idan Gazit

Attachment: code_grey.png added

Documentation with a monochrome code block background

comment:2 Changed 5 years ago by Idan Gazit

I'm not a huge fan of the green background for code samples, however I don't think it qualifies as "barely legible." I'm loath to touch something that has worked fine for many people, or at least, has failed to elicit comment from them.

That being said, I've attached two screenshots, one depicting the current state of affairs, and one with a grey-background for code blocks.

I'd like to see a docs style refactor in a future django, might as well think about this aspect now.

Opinions welcome!

comment:3 Changed 5 years ago by Idan Gazit

Apologies, unclear "next step":

I'll leave this open to comment for a month. Absent engaged discussion, I'll make some decision on Dec 1st or the 1.4 deadline, whichever comes first.

comment:4 Changed 5 years ago by Idan Gazit

Component: Djangoproject.com Web siteDocumentation

Changed 5 years ago by shaunkelly

Attachment: contrasty_text.png added

comment:5 Changed 5 years ago by shaunkelly

It's more the text colors than the background color that makes it harder to read, particularly the comment/keyword grey, and the light blue and yellow. In fact the grey is probably less readable on a grey background. I attached a quick mockup replacing those colors with more saturated versions for a little more contrast.

Though, besides the comments, I wouldn't classify it as barely legible either.

comment:6 Changed 5 years ago by Claude Paroz

Interesting resources:

I tested for example the color values of brown text on green background. It fails miserably :-(

comment:7 Changed 5 years ago by jimallman <jim@…>

An easy alternative is to adjust the background color used for code samples. A tint used over large areas doesn't need to be so dark/intense.

In this case, #F3FFE5 works pretty well in my opinion, and comments and keywords don't disappear.

comment:8 Changed 5 years ago by Idan Gazit

Resolution: wontfix
Status: newclosed
Triage Stage: Design decision neededSomeday/Maybe

I feel like this is a bikeshed, and the actual problem is not so grave. None of the existing solutions (mine included) is a significant improvement over the original, and I'd rather see some thought applied towards revamping the sphinx theme of the docs—a part of which will be giving some love to the styling of code blocks in the context of the new style.

Thanks all for your thoughts, I've bookmarked this ticket for when that day comes. If you'd like to see this move forward, the next step is a concrete proposal which outlines the larger problems with / potential improvements to the existing docs. It doesn't need to offer solutions, but it does need to scope out the issues we should tackle.

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