API Docs Visual Refresh

[Therenas]

Hello everyone, we’ve been working on a design refresh of the API docs. There were a couple of big and many small problems that we wanted to address to improve readability and usability. The functionality and content stayed mostly the same, this was mainly about presentation. The redesign was also done with an eye towards being a good foundation for the coming prototype docs.

Hopefully, this overhaul improves your experience with the docs. They are still not perfect, of course, so use this thread to bring up any issues you notice, or present any suggestions to further improve the docs. This is explicitly not for issues with the content of the docs, use this thread for that.

Also, we’d especially appreciate feedback on the performance of the website. The previous design had issues with scroll-lag, particularly on less powerful mobile devices. Changes were made to mitigate these, but it’s hard to conclusively test this, so please let us know how the new design performs for you.

Known Issues:

• Layout on mobile does not work well, and cuts off text in many situations.

[Pi-C]

There used to be a button that would allow to sort the list of properties/methods alphabetically. I've used that a lot because the natural order seems quite arbitrary, which makes it easy to miss a property while scanning the list. Could we get that button back, please?

[InappropriatePenguin]

Having played around with the new design some more, I really miss the blue color used in the previous design for links (and throughout the Factorio homepage) over the new brown one. The latter just feels a lot harder to read. I would suggest either using the old blue color or increasing the brightness of the brown color used, such that there's greater contrast with the background.

I had mentioned in the discord my suggestion to indent the 2nd+ lines if they end up wrapping. I'll just clarify that I only intended for that suggestion to apply to the method-name column. The wrapping style for the other columns is good as-is.

The refresh certainly feels a lot more performant so thanks for that!

[Pi-C]

The site looks weird with qutebrowser. Apparently, there is a table with column for name, type, and description. Most of the time, the last column is duplicated on a new line. This doesn't happen if only the first column contains text -- see the red box in the screenshot:

api-site.png (357.9 KiB) Viewed 2125 times

Torbrowser displays the page as expected, without duplicating the last column.

-> [Therenas] This was due to stale cache, and should be fixed for everyone now.

[PFQNiet]

I'm going to second InappropriatePenguin's comment about link colours. It was the very first thing I noticed, and after checking I see it has a contrast ratio of 4.1 with the grey background. Given the relatively thin font weight, this makes it a big fail for accessibility/legibility. It doesn't just "feel a lot harder to read", it mathematically is!

[LuziferSenpai]

Hey,

so I would recommend using

Code: Select all

.docs-table p {
    line-height: 1.1;
    word-break: break-word;
}

So that on smaller screens this doesnt happen.

chrome_eNZy9l8uuw.png (225.99 KiB) Viewed 1942 times

Greetz,

Luzifer