Playing with a new theme for the docs, iteration 2

[Michael Urman]

On Sun, Mar 25, 2012 at 07:07, Antoine Pitrou <[hidden email]> wrote:
>>
>> I've also added a little questionable gimmick to the sidebar (when you collapse
>> it and expand it again, the content is shown at your current scroll location).
>
> The gimmick is buggy (when you collapse then expand it in the middle,
> and then scroll up, the sidebar content disappears after scrolling),
> and in the end quite confusing.

It also seems not to handle window resizes very well right now. It
appears to choose the height for the vertical bar when shown, and then
when the text next to it reflows to a new length, the bar can become
longer or shorter than necessary.

On the one hand this makes it hard to get the sidebar content to show
at the bottom of the page; on the other, I believe it mitigates
potential problems if sidebar content is too long for the window size.

--
Michael Urman
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%2B1324100855712-1801473%40n6.nabble.com

[Ned Batchelder]

On 3/25/2012 2:34 AM, Georg Brandl wrote:
> Here's another try, mainly with default browser font size, more contrast and
> collapsible sidebar again:
>
> http://www.python.org/~gbrandl/build/html2/
Georg, thanks so much for taking on this thankless task with grace and
skill.  It can't be easy dealing with the death by a thousand tweaks,
and I know I've contributed to the flurry.

Nowhere on the page is a simple link to the front page of python.org.  
Perhaps the traditional upper-left corner could get a bread-crumb before
"Python v3.3a1 documentation" that simply links to python.org.  Maybe,
use the word Python that is already there:  [Python] » [v3.3a1
documentation].  People do arrive at doc pages via search engines, and
connecting the docs up to the rest of the site would be a good thing.

Speaking of links to other pages, the doc front page, under "Other
resources" lists Guido's Essays and New-style Classes second and third.  
These each point to extremely outdated material ("Unifying types and
classes in 2.2", and "Unfortunately, new-style classes have not yet been
integrated into Python's standard documention." ??).  Another, "Other
Doc Collections," points to an empty apache-style directory listing  
:-(.  These links should be removed if we don't want to keep those
sections of the site up-to-date.  I know this is not strictly part of
the redesign, but I just noticed it and thought I would throw it out there.

I agree about the outlined style for "New" notices, and the red for
deprecation is extremely alarming! :)

I'll make one last plea for not justifying short paragraphs full of
unbreakable elements, but I know I am in the minority.

> I've also added a little questionable gimmick to the sidebar (when you collapse
> it and expand it again, the content is shown at your current scroll location).
I especially like using dynamic elements on a page to adapt to a
reader's needs. I have some other ideas that I'll try to cobble together.

--Ned.
> Have fun!
> Georg
>
> _______________________________________________
> Python-Dev mailing list
> [hidden email]
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: http://mail.python.org/mailman/options/python-dev/ned%40nedbatchelder.com
>
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%2B1324100855712-1801473%40n6.nabble.com

[Tim Golden-4]

On 25/03/2012 16:26, Ned Batchelder wrote:
> Georg, thanks so much for taking on this thankless task with grace and
> skill. It can't be easy dealing with the death by a thousand tweaks

Seconded. I'm constantly edified by the way in which people
in the community respond to even quite abrupt criticism in
a constructive, open and often humorous manner. (As I've said
before, I'm also impressed by the way in which people are prepared
to come back and apologise / acknowledge that they had a moment
of jerkiness).


TJG
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%2B1324100855712-1801473%40n6.nabble.com

[Terry Reedy]

On 3/25/2012 2:34 AM, Georg Brandl wrote:
> Here's another try, mainly with default browser font size, more contrast

Untrue. You still changed the high contrast dark blue to the same low
contrast light blue for builtin names, etc. What problem do you think
you are trying to solve by making the doc difficult and even PAINFUL for
me to read?

- a lot more than 1

--
Terry Jan Reedy

_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%2B1324100855712-1801473%40n6.nabble.com

[Stefan Krah-3]

Stephen J. Turnbull <[hidden email]> wrote:
> Not with just a header.  http://turnbull.sk.tsukuba.ac.jp/Teach/IntroSES/
> is a (very primitive and not stylistically improved in years) example
> of a frame-based layout that I use some of my classes.  I would
> put a search field in the top frame (if I had one. :-)  But I suppose you
> would find the fixed sidebar distracting.

No, if the whole sidebar is fixed I don't mind (though I'm not a fan of
frames). The top frame takes up space though.


> > In general fixed elements distract me
> > greatly. This also applies to the '<<' element in the collapsible
> > sidebar. When I'm scrolling, it's almost the center of my attention
> > (when I should be focusing on the text).
>
> I suspect you're unusual in that, but I guess it just is going
> to bug you no matter what, and I personally don't have
> *that* strong a preference either way.

Maybe. It's hard to determine. It's just that I don't see fixed search
boxes or fixed elements like '<<' on big name websites (who may or may
not have usability departments). So it is at least possible that such
features have always been controversial.


Stefan Krah



_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%2B1324100855712-1801473%40n6.nabble.com

[Georg Brandl-2]

On 25.03.2012 09:19, Ben Finney wrote:

> Georg Brandl <[hidden email]> writes:
>
>> Here's another try, mainly with default browser font size, more
>> contrast and collapsible sidebar again:
>>
>> http://www.python.org/~gbrandl/build/html2/
>
> Great! You've improved it nicely. I especially like that you have
> <URL:https://en.wikipedia.org/wiki/Unobtrusive_JavaScript> done the
> collapsible sidebar with graceful degradation: the content is quite
> accessible without ECMAscript.
>
> Can you make the link colors (in the body and sidebar) follow the usual
> conventions: use a blue colour for unvisited links, and a purple colour
> for visited links <URL:http://www.useit.com/alertbox/20040510.html> so
> it's more obvious where links are and where the reader has already been.

Thanks.  Same colors for visited and unvisited links is indeed an oversight
on my part.  I'll put that in the final version.

Georg

_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%2B1324100855712-1801473%40n6.nabble.com

[Georg Brandl-2]

On 25.03.2012 10:06, Peter Otten wrote:

> Georg Brandl wrote:
>
>> Here's another try, mainly with default browser font size, more contrast
>> and collapsible sidebar again:
>>
>> http://www.python.org/~gbrandl/build/html2/
>
> Nice! Lightweight and readable.
>
>>From the bikeshedding department:
>
> * Inlined code doesn't need the gray background. The bold font makes it
> stand out enough.
> * Instead of the box consider italics or another color for [New in ...]
> text.

Yes, I'll revert to italics as most people don't seem to like the colored boxes.

> * Nobody is going to switch off the prompts for interactive sessions.

You'll laugh, but that was a pretty often-wished feature so that copy-paste
gets easier.  It'll certainly stay.

> * Maybe the Next/Previous Page headers on the left could link to the
> respective page.

I see no reason since the links below already do.

> * Short descriptions in the module index don't need italics.
> * The disambiguation in the index table could use a different style instead
> of the parentheses.

These two would need to be changed in Sphinx.

Georg

_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%2B1324100855712-1801473%40n6.nabble.com

[Georg Brandl-2]

On 25.03.2012 17:26, Ned Batchelder wrote:

> On 3/25/2012 2:34 AM, Georg Brandl wrote:
>> Here's another try, mainly with default browser font size, more contrast and
>> collapsible sidebar again:
>>
>> http://www.python.org/~gbrandl/build/html2/
> Georg, thanks so much for taking on this thankless task with grace and
> skill.  It can't be easy dealing with the death by a thousand tweaks,
> and I know I've contributed to the flurry.
>
> Nowhere on the page is a simple link to the front page of python.org.  
> Perhaps the traditional upper-left corner could get a bread-crumb before
> "Python v3.3a1 documentation" that simply links to python.org.  Maybe,
> use the word Python that is already there:  [Python] » [v3.3a1
> documentation].  People do arrive at doc pages via search engines, and
> connecting the docs up to the rest of the site would be a good thing.

Indeed.  I'm trying to tweak that right now.

> Speaking of links to other pages, the doc front page, under "Other
> resources" lists Guido's Essays and New-style Classes second and third.  
> These each point to extremely outdated material ("Unifying types and
> classes in 2.2", and "Unfortunately, new-style classes have not yet been
> integrated into Python's standard documention." ??).  Another, "Other
> Doc Collections," points to an empty apache-style directory listing  
> :-(.  These links should be removed if we don't want to keep those
> sections of the site up-to-date.  I know this is not strictly part of
> the redesign, but I just noticed it and thought I would throw it out there.

That would be best to capture in a bugs.python.org issue, I think.

> I agree about the outlined style for "New" notices, and the red for
> deprecation is extremely alarming! :)

Changed.

> I'll make one last plea for not justifying short paragraphs full of
> unbreakable elements, but I know I am in the minority.

:)

>> I've also added a little questionable gimmick to the sidebar (when you collapse
>> it and expand it again, the content is shown at your current scroll location).
> I especially like using dynamic elements on a page to adapt to a
> reader's needs. I have some other ideas that I'll try to cobble together.

That would be great.

Georg

_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%2B1324100855712-1801473%40n6.nabble.com

[Georg Brandl-2]

On 25.03.2012 17:54, Terry Reedy wrote:
> On 3/25/2012 2:34 AM, Georg Brandl wrote:
>> Here's another try, mainly with default browser font size, more contrast
>
> Untrue. You still changed the high contrast dark blue to the same low
> contrast light blue for builtin names, etc. What problem do you think
> you are trying to solve by making the doc difficult and even PAINFUL for
> me to read?
>
> - a lot more than 1

"More contrast" was meant in comparison to iteration #1.

Hmm, don't you think you'll get used to the new style in a while? The link
color is not actually that light in comparison.  Of course you can always
use a user stylesheet to override our choices.

Georg

_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%2B1324100855712-1801473%40n6.nabble.com

[Georg Brandl-2]

On 25.03.2012 13:09, Stephen J. Turnbull wrote:

> On Sun, Mar 25, 2012 at 11:04 AM, Stefan Krah <[hidden email]> wrote:
>
>> Do you mean a fixed search box like this one?
>>
>> http://coq.inria.fr/documentation
>>
>> Please don't do this, I find scrolling exceptionally distracting in the
>> presence of fixed elements.
>
> Does it bother you when the header is fixed and contains
> the search box?  I prefer that arrangement, anyway.

I think this idea has some merit.  I'd prefer it to be tried out and implemented
in a second step though (maybe by someone else, even? ;)

Georg

_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%2B1324100855712-1801473%40n6.nabble.com

[Georg Brandl-2]

On 25.03.2012 08:34, Georg Brandl wrote:
> Here's another try, mainly with default browser font size, more contrast and
> collapsible sidebar again:
>
> http://www.python.org/~gbrandl/build/html2/
>
> I've also added a little questionable gimmick to the sidebar (when you collapse
> it and expand it again, the content is shown at your current scroll location).

Thanks everyone for the overwhelmingly positive feedback.  I've committed the
new design to 3.2 and 3.3 for now, and it will be live for the 3.3 docs
momentarily (3.2 isn't rebuilt at the moment until 3.2.3 final goes out).
I'll transplant to 2.7 too, probably after the final release of 2.7.3.

Please make further suggestions (preferably with patches) through the bug
tracker.

cheers,
Georg

_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%2B1324100855712-1801473%40n6.nabble.com

[Matt Joiner]

Not sure if you addressed this in your answers to other comments...

Scroll down the page. Minimize the nav bar on the left. Bring it back
out again. Now the text in the nav bar permanently starts at an offset
from the top of the page.

On Sun, Mar 25, 2012 at 7:44 PM, Matt Joiner <[hidden email]> wrote:
> Is nice yes?! When I small the nav bar, then embiggen it again, the text
> centers vertically. It's in the wrong place. The new theme is very minimal,
> perhaps a new color should be chosen. We've done green, what about orange,
> brown or blue?
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%2B1324100855712-1801473%40n6.nabble.com

[Steven D'Aprano-8]

Georg Brandl wrote:

> Thanks everyone for the overwhelmingly positive feedback.  I've committed the
> new design to 3.2 and 3.3 for now, and it will be live for the 3.3 docs
> momentarily (3.2 isn't rebuilt at the moment until 3.2.3 final goes out).
> I'll transplant to 2.7 too, probably after the final release of 2.7.3.

I think it would be better to leave 2.7 with the old theme, to keep it
visually distinct from the nifty new theme used with the nifty new 3.2 and 3.3
versions.



--
Steven
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%2B1324100855712-1801473%40n6.nabble.com

[Georg Brandl-2]

On 25.03.2012 21:09, Matt Joiner wrote:
> Not sure if you addressed this in your answers to other comments...
>
> Scroll down the page. Minimize the nav bar on the left. Bring it back
> out again. Now the text in the nav bar permanently starts at an offset
> from the top of the page.

Yes, that was the intention I mentioned in my post.

That has been removed though from the final version I checked in.  There
are certainly much better solutions.

Georg

_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%2B1324100855712-1801473%40n6.nabble.com

[Georg Brandl-2]

On 25.03.2012 21:11, Steven D'Aprano wrote:

> Georg Brandl wrote:
>
>> Thanks everyone for the overwhelmingly positive feedback.  I've committed the
>> new design to 3.2 and 3.3 for now, and it will be live for the 3.3 docs
>> momentarily (3.2 isn't rebuilt at the moment until 3.2.3 final goes out).
>> I'll transplant to 2.7 too, probably after the final release of 2.7.3.
>
> I think it would be better to leave 2.7 with the old theme, to keep it
> visually distinct from the nifty new theme used with the nifty new 3.2 and 3.3
> versions.

Hmm, -0 here.  I'd like more opinions on this from other devs.

Georg

_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%2B1324100855712-1801473%40n6.nabble.com

[Andrew Svetlov]

I like to see new schema only for 3.3 as sign of shiny new release.

On Sun, Mar 25, 2012 at 10:25 PM, Georg Brandl <[hidden email]> wrote:

> On 25.03.2012 21:11, Steven D'Aprano wrote:
>> Georg Brandl wrote:
>>
>>> Thanks everyone for the overwhelmingly positive feedback.  I've committed the
>>> new design to 3.2 and 3.3 for now, and it will be live for the 3.3 docs
>>> momentarily (3.2 isn't rebuilt at the moment until 3.2.3 final goes out).
>>> I'll transplant to 2.7 too, probably after the final release of 2.7.3.
>>
>> I think it would be better to leave 2.7 with the old theme, to keep it
>> visually distinct from the nifty new theme used with the nifty new 3.2 and 3.3
>> versions.
>
> Hmm, -0 here.  I'd like more opinions on this from other devs.
>
> Georg
>
> _______________________________________________
> Python-Dev mailing list
> [hidden email]
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: http://mail.python.org/mailman/options/python-dev/andrew.svetlov%40gmail.com

--
Thanks,
Andrew Svetlov
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%2B1324100855712-1801473%40n6.nabble.com

[Maciej Fijalkowski]

On Sun, Mar 25, 2012 at 9:25 PM, Georg Brandl <[hidden email]> wrote:

> On 25.03.2012 21:11, Steven D'Aprano wrote:
>> Georg Brandl wrote:
>>
>>> Thanks everyone for the overwhelmingly positive feedback.  I've committed the
>>> new design to 3.2 and 3.3 for now, and it will be live for the 3.3 docs
>>> momentarily (3.2 isn't rebuilt at the moment until 3.2.3 final goes out).
>>> I'll transplant to 2.7 too, probably after the final release of 2.7.3.
>>
>> I think it would be better to leave 2.7 with the old theme, to keep it
>> visually distinct from the nifty new theme used with the nifty new 3.2 and 3.3
>> versions.
>
> Hmm, -0 here.  I'd like more opinions on this from other devs.
>
> Georg

I would definitely like the new theme on 2.7 docs as well, since 2.7
is still supported.

Cheers,
fijal
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%2B1324100855712-1801473%40n6.nabble.com

[Brian Curtin]

On Sun, Mar 25, 2012 at 14:50, Andrew Svetlov <[hidden email]> wrote:
> I like to see new schema only for 3.3 as sign of shiny new release.

Please don't do this. It will result in endless complaints.
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%2B1324100855712-1801473%40n6.nabble.com

[Ben Finney-10]

Brian Curtin <[hidden email]> writes:

> On Sun, Mar 25, 2012 at 14:50, Andrew Svetlov <[hidden email]> wrote:
> > I like to see new schema only for 3.3 as sign of shiny new release.
>
> Please don't do this. It will result in endless complaints.

Complaints of what nature? Do you think those complaints are justified?

--
 \            “… Nature … is seen to do all things herself and through |
  `\         herself of own accord, rid of all gods.” —Titus Lucretius |
_o__)                                                 Carus, c. 40 BCE |
Ben Finney

_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%2B1324100855712-1801473%40n6.nabble.com

[Terry Reedy]

On 3/25/2012 12:32 PM, Georg Brandl wrote:

> On 25.03.2012 17:54, Terry Reedy wrote:
>> On 3/25/2012 2:34 AM, Georg Brandl wrote:
>>> Here's another try, mainly with default browser font size, more contrast
>>
>> Untrue. You still changed the high contrast dark blue to the same low
>> contrast light blue for builtin names, etc. What problem do you think
>> you are trying to solve by making the doc difficult and even PAINFUL for
>> me to read?
>>
>> - a lot more than 1
>
> "More contrast" was meant in comparison to iteration #1.

It is still subjectively dim enough to me that I could not tell from memory.

I ran the following experiment: I put old and new versions of the buitin
functions page side-by-side in separate browser windows. I asked my
teenage daughter to come into the room, approach slowly, and say when
she could read one or both windows. At about 5 feet, she could (just)
read the old but not the new.

If other people repeat the experiment and get the same result, it would
then be fair to say that the new style is objectively less readable in
regard to this one aspect.

> Hmm, don't you think you'll get used to the new style in a while?

This is a bit like asking a wheelchair user if he would get used to
having a ramp ground down to add little one-inch steps every two feet,
because leg-abled people found that somehow more aesthetic.

Answer: somewhat.

Wired magazine has used a similar thin blue font. I got used to that by
ignoring any text written with it.

 > The link color is not actually that light in comparison.

Using a magnifying glass, the difference seems to be more one of
thickness -- 2 pixel lines versus 1-1.5 pixel lines. I have astigmatism
that is only partly correctable and the residual blurring of
single-pixel lines tends to somewhat mix text color with the background
color.

> Of course you can always use a user stylesheet to override our choices.

Can anyone tell me the best way to do that with FireFox?
Is it even possible with the Windows help version, which is what I
usually use?

--
Terry Jan Reedy

_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%2B1324100855712-1801473%40n6.nabble.com