Greetings,
The Python docs is more than a language reference. The how to sections and FaQ
are nice pieces also. However, though i like the content, i find the style and theme
bland, with a reminder of an ancient time in the web sphere.
I suggest we consider changing the theme to a crisper and cleaner look.
I find docs such as Masonite really enjoyable to read in terms of style:
-link removed-
I posted on Python-ideas, but it was not the place. Here is a summary of the mailing list thread responses (excuse links, new users cannot post more than 2 links):
M.-A. Lemburg:
In particular, it would make sense to bring the themes of the
main python.org website and the docs.python.org site closer
together, as there is a fairly dramatic break between the
two at the moment.The same goes for the devguide -link removed- and the wiki -link removed-
-link removed- is already a lot closer to the -link removed-
design and looks even fresher (it was launched in 2017, some time
after python site -link removed-, which was relaunched in 2014).
Holly Short:
As someone who does both Web design and Python regularly, I’d love to contribute to reworking/changing the Python docs theme.
They are not terrible currently, there are certainly areas for improvement, both in overall layout and text styling. Bringing it closer to other Python branding may also be desirable.
For me, the quality of a project’s website is a major factor in whether or not I use it. If it looks old or badly styled, it is an indicator that there may not much be active development in the project. I apply this less to languages, as they are generally spoken about enough that one can use their reputation, but I can well imagine someone turning away from a language because the docs felt old or badly styled.
Jeff Allen:
The visual style is quite like the existing Python docs prepared in ReST (e.g. docs -link removed-). The Sphinx “Alabaster” theme is even cleaner, but intended in part, I think, as a blank canvas for your branding. I prefer the way the sidebar scrolls independently in the Masonite site. I found no examples of images, diagrams or tables to compare. I would not say there was much wrong with the Python visual style, but then I’m used to spending hours in the (downloaded) documentation.
Is it really just GitBook that we are slightly admiring? You would not, I think, want to re-write the ReST documents in GitBook, just to get a cleaner look. Time from someone clever with CSS in Sphinx may be all it takes.
If you follow the documentation link on the home page to -link removed-, much of that links to the wiki, which in my opinion does look a bit cobwebby. Style is only part of problem: the size and proportions of text look pokey to me. Here the content does not read very well, being crowd-sourced I imagine without much editorial control. (E.g. wiki -link removed- is unsure of its level: veering from “if you’ve never programmed before” through to inviting patches.) Were we including the Wiki in this?
Paul Bryan:
How can this effort avoid merely addressing subjective preferences? Beauty in the eye of the beholder, and all that.
This appears to be the current style guide:
devguide -link removed-
It largely focuses on content. Would it be worth codifying additional aesthetic and usability objectives, and build consensus around them?
Are there other sites that have refreshed their styles we can learn from? For example, Wikipedia did a refresh diff wikimedia -link removed-
Mike Miller:
The current docs theme is decent I think. Liked your link to the masonite docs
theme slightly better, though not hugely different. However!One thing that drives me nuts about the current Python docs theme is
the FULL JUSTIFICATION that adds random spaces into each line to make the
edges line up!Whatever y’all do, please remove that.
I sometimes deactivate it in the
browser dev tools but there it is again next refresh.
Jonathan Goble:
Please. Full justification is nice with narrow columns like newspapers, but on the web with wider paragraphs, it’s annoying. I’d love to see it yanked from the Python docs.
Neil Girdhar:
Also, I think the Masonite docs’ navigation is far superior to the Python docs. I like the full contents on the left, along with the version button, and the local jump on the right. The python docs require you to navigate somehwere else for the full contents. And, I don’t undrstand why anyone would want “previous topic/next topic”—it’s not like you’re curling up with the Python docs before bed
Finally, putting the docs in the center of the screen is better on today’s giant monitors.
Stephen Turnbull:
Paul Bryan writes:
It largely focuses on content. Would it be worth codifying additional
aesthetic and usability objectives, and build consensus around
them?We’re literally talking about painting a bikeshed! Just do it, and if
people don’t like it enough it gets rolled back.
Notes:
I posted a message sometimes back on python-list about changing
the theme of the Python docs. I was pointed out to the docs list. Upon posting
there, Julien Palard pointed to me some ongoing works as outlined by the recent
release thread. However the idea i proposed there did not receive responses other than
that. On the python-ideas you’ve had responses, volunteers but there it was not the
place to discuss it.
And the current release does not change the theme, it fixes some issues other than styling.
