API Docs Visual Refresh

Place to report issues and suggest improvements to the API documentation.
Post Reply
User avatar
Therenas
Factorio Staff
Factorio Staff
Posts: 232
Joined: Tue Dec 11, 2018 2:10 pm
Contact:

API Docs Visual Refresh

Post by 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
Smart Inserter
Smart Inserter
Posts: 1639
Joined: Sun Oct 14, 2018 8:13 am
Contact:

Re: API Docs Visual Refresh

Post by 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?
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

InappropriatePenguin
Inserter
Inserter
Posts: 29
Joined: Mon Sep 13, 2021 6:53 pm
Contact:

Re: API Docs Visual Refresh

Post by 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
Smart Inserter
Smart Inserter
Posts: 1639
Joined: Sun Oct 14, 2018 8:13 am
Contact:

Re: API Docs Visual Refresh

Post by 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
api-site.png (357.9 KiB) Viewed 1360 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.
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

PFQNiet
Filter Inserter
Filter Inserter
Posts: 289
Joined: Sat Sep 05, 2020 7:48 pm
Contact:

Re: API Docs Visual Refresh

Post by 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!

User avatar
LuziferSenpai
Filter Inserter
Filter Inserter
Posts: 333
Joined: Tue Jul 08, 2014 10:06 am
Contact:

Re: API Docs Visual Refresh

Post by 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
chrome_eNZy9l8uuw.png (225.99 KiB) Viewed 1177 times
Greetz,

Luzifer
Coding is awesome!
Animes are love!
Factorio is life!

My MODs:
Click

Greetz,

Senpai

Post Reply

Return to “Documentation Improvement Requests”