First off, I view the docs on a 1080x1920 screen. A lot of programmers use vertical displays, and they’re pretty common as secondary displays (which is where documentation is often read).
This is the old Docs site’s BasePart page, on my vertical screen, at 100% page zoom.
Complaint 1: The new site is far less usable on vertical screens - there’s a lot of content on the old page, and there’s a lot less content on the new page, for no apparent reason. To get the content of the page to display without scrolling, I have to zoom out to 70%, which looks like this:
I’m a young person with good eyesight, and I have a lot of trouble reading that at a healthy view distance from my (24") screen. I can’t imagine how bad it would be for someone who has vision issues or a smaller monitor.
Complaint 2: The new Docs site needs this button:
I can hide the content itself by collapsing the first heading, but there’s no way to recover the space for other content. The old site allows the collapse of the entire section of the page and will put text there.
Will this mean that non-Instance types and libraries will be better documented? This led to outdated/nonexistent documentation in the old site for extended periods of time because anything that wasn’t an instance could not be automatically updated.
Hey, can you give me the specs of the computer you’re using to browse the new Docs Site? We’ve been actively looking into performance, so knowing that would be very helpful.
CPU: Intel Core i7-10700 @ 2.90 GHz
16 GB RAM
GPU: NVIDIA GeForce GTX 1660 SUPER (6 GB of video memory)
256 GB SSD (this is where Windows is installed) and a 1 TB HDD (for extra storage)
Also running on Google Chrome version 101.0.4951.67 (latest version as of right now)
I think that should be enough.
While unifying the API is a great thing, I don’t believe the new site improves the readability, quite the opposite.
The lack of color, lack of clear divisions between sections, too much white space… this is going to be harder to work with. Please take your time and restructure the layout and colors to aim for maximum readability.
My Suggestion: Theme Options
Example features could include:
Light Mode
Compact Reading Mode (Reduces unnecessary white space)
Reason for suggestion:
Far too much white space – Seemingly over half of each page is comprised of line spacing. Maybe to some it looks nice, but it decreases productivity and usability. When developers use these documentation pages, having immediate access to the information we need is the most important aspect.
Also, a light theme would be nice. I do not like dark mode & avoid it when possible. I’m not forced to use it in studio, on the main website, or devforum - So, why am I on the new pages being designed? For me, light-mode themed websites are more pleasant to look at & have increased readability.
The website is great at this point. However, it is missing some features like automatic theme switching, improved accessibility, and using dark theme scrollbars.
Theme switching
Simply using the prefers-color-scheme media query to automatically change the theme to what the user has set their device theme to is the most accessible and simplest way.
An accessibility issue I noticed is that website has a lot of animated transitions but doesn’t use the prefers-reduced-motion media query to disable it the user has reduced motion enabled on their device.
Improved dark mode
Lastly for improved dark mode support by specifying the color-scheme as dark light with the default scheme being the one listed first would mean that in dark mode the browser style sheet supports dark and light appearance (defaulting to dark), so native elements like scrollbars, inputs, etc will use a dark appearance if that’s what the user has their device set to. If there is no light theme planned, using just dark as the value should be used instead.
Lasty, using it on mobile is a subpar experience. Instead of the main content being part of the page body that scrolls, the scrollable content is inside a flexbox container. So, this means you have two scroll bars that appear, you have to scroll the box and then the page to reach the footer, and browser features like minimizing the tab bar when scrolling doesn’t work.
This is bad for accessibility, and it leads to a bad experience on mobile. It’s not great on desktop either having the main content in that box, as that means you need to focus on it before you can scroll the page, which is bad practice.
