improve documentation legibility

[drc0]

This is only an idea, and eventually it could be improved a lot, but most of the issues with the documentation legibility I think are those

• color contrast is not sufficient to distinguish links from text
• there is an effect of "box in a box in a box" further accentuated by box-shadows and borders that distracts instead of helping separating element types
• various shadows, like snippet boxes have borders that accentuate that boxed content effect
• the sidebar has a color that distracts from the main content
• there are issues with the header that repeats the same informations in multiple places

this is an experiment for this page https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html that addresses those issues and I would like some feedback for this direction before proposing a simple patch

[zzzeek]

i can go without drop shadows, though some background on that would be useful, though the "borderless"-ness seems a little jarring. at least in your mockup, you have a different white on the left nav than the background so there is this subtle change in white without any border, so i think maybe you meant to have the white border just the same as background color, again using https://dev.mysql.com/doc/refman/8.0/en/json.html as a general guide for "large corporate site designed by real web designers". they have no drop shadows, OK but they do have a very simple crisp line border around inner boxes. I think (again an accessibility expert would know more here) having a black line border around a box means the eye can use that black line to know "this is a separate sidebar thing" vs. having to distinguish between two color shades. But that's just my guessing.

[zzzeek]

here's a shot of my fastmail window which does use a grey background for the side menu, not as deeply grey, also some drop shadows, but not inline with text.

[drc0]

Great! The important thing here is that we agree on the type of changes I can propose, which should be focused on improving the documentation look rather than a complete redesign. The proposed improvements should address the issues I listed above and include a better proposal that is similar to the screenshot I provided, clearly addressing the point you highlighted.

I understand that you would like to give the documentation a more "corporate" look, with a focus on legibility and clarity. While I am not a UX designer, I have worked as a web developer for many years and believe that I can propose a patch that meets these goals. If you are interested in the direction I can propose, I am happy to move forward.

[zzzeek]

it would be better if we could make relatively small changes incrementally, like three or four CSS changes per patch, not sure how much you had in mind.

[drc0]

@zzzeek sure, that would be the direction. What is the better way for me to test the integration with the website and also propose a header change there?

[zzzeek]

the website integration is kind of several steps, which ....I definitely wrote it out somewhere recently.

well start with the site which is at https://github.com/sqlalchemyorg/sqlalchemyorg/, and there's a bash script in the readme that is the steps to run the main sqlalchemyorg site. to integrate (somewhat) with the docs, you want to edit _config.py to have "//localhost:8080/docs" for the docs site and "localhost:8000" for the main site; then run the sqlalchemyorg site on port 8000 (do zeekofile --serve 8000).

Next, go to the SQLA docs and build them with READTHEDOCS=True and RTD_SITE_BASE=http://localhost:8000, then do a "make clean autobuild" that will listen on port 8080 for the docs site.

[zzzeek]

just to clarify, when you do "make autobuild", the actual sphinx build process will contact localhost:8000 to pull down some JS and CSS from the "main" site. then it builds statically. so the site is static, but the sphinx build process uses a web service some static files that are part of the sqlalchemyorg site build to get the main site's layout at build time. that's what the original purpose of zzzeeksphinx was.

[drc0]

I've prepared a set of commits for which I'm still not doing any PR but you can see them here https://github.com/drc0/zzzeeksphinx/tree/fix/themeimprovements https://github.com/drc0/sqlalchemyorg/tree/fix/themelegibility

also here is a before and after and a rationale behind the changes (opening both in the browser with a 100% scale helps evaluating them):

• removed box shadows from the main body and various boxes, leaving subtle borders to separate the content without creating too much boxes that distract the attention
• fixed the link color that was with little to no contrast
• improved the sidebar by removing the gray bg and working on the font sizes, colors, link reachability (the whole line is clickable and not the precise text), the gray bg was too distracting from the main content
• the sidebar menu has better title separation, before it was not clear the separation from section title and page links
• the docs body and sidebar are more spaced (space and gray line)
• the sidebar popout (the element before the ads top left) now has only doc link and search, removing the version/release and title that are on the main header
• the main header has been improved, it occupies less space and attention, the font size has been reduced, so various margins and mobile styles has been reworked
• given docs are often 'skimmed'.. a good way to separate various parts is to work on spaces instead of lines, I removed most 'boxes' but worked on title and text spaces so the sections are more visible
• the 'pre' element, and various boxes have better colors that do not separate them from the content too much (here postgres docs helped as benchmark)
• the footer has previous/next links more visible and the copyright bg has been removed for the same reason
• the main header menu as a better bg color, here removing the shadow helps only on the modern look
• for the future -> try finding a better bg image behind the ' The Database Toolkit for Python ' motto, I left that because it is too distinctive for the brand
• also, if there is a logo not truncated on the bottom I would advise to put it on the hader and give it more space for 'branding' purposes

[zzzeek]

wow I like this a lot! esp the nav stuff which I was always not comfortable with (the way it had two "SQLAlchemy 2.0 Documentation" links, that kind of happened due to Sphinx layout defaults). interesting decisions such as losing the colored box around the copyright stuff also, I see why though. I dont know how much of this came from whatever sphinx theme we copied originally.

this week I have some critical code issues that have to get released so it may be a few days before I can look closely at these changes but I think these will help the site a lot, and I appreciate the deep attention to detail that we usually don't get from most contributions :)

[drc0]

Glad you liked it, so I've opened two related PR, feel free to comment on them and close this issue accordingly when you have time, thanks!