New API Docs website

Place to post guides, observations, things related to modding that are not mods themselves.
curiosity
Long Handed Inserter
Long Handed Inserter
Posts: 81
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: New API Docs website

Post by curiosity »

Sanqui wrote:
Fri Sep 03, 2021 1:50 pm
The old web had to go
Just to clarify, you mean the backend and you took this opportunity to redesign the frontend, or was there something objectionable about the old design?

Solinya
Long Handed Inserter
Long Handed Inserter
Posts: 77
Joined: Sun Mar 17, 2019 10:39 pm
Contact:

Re: New API Docs website

Post by Solinya »

I agree with Hornwitser. Unless I'm missing some secret way to hide the class list on the left, the actual documentation section gets scrunched into a much smaller horizontal space than the old docs layout, which means I can't fit nearly as much info on my laptop's screen. I'd prefer to have the navigation and documentation separated out in some manner, because I'm generally not navigating and reading at the same time, I'm doing one or the other. I'd feel differently if the navigation was for subsections on the current entry, especially for the long entries like LuaControl, but I don't need to e.g. see all events while trying to read the details of a LuaControl method.

Also the visual style on the new documentation is very busy with all the table lines and borders everywhere (not to mention the smaller width leads to more word wrapping, especially on the methods and parameter tables, which also leads to visible unaligned table column separators). The bold yellow on medium-gray I find harder to read than the orange on dark gray. I think this is actually more because of the lighter shade of gray used on the inner table rather than the yellow as either of the other grays on the table layout are easier to read as a background.

It is nice that the new docs come with a search box, but I tried searching for the info I'm often trying to reference and immediately discovered it doesn't search properties and methods, which was disappointing. Hopefully there are plans to expand the search capabilities in the future.

Hornwitser
Fast Inserter
Fast Inserter
Posts: 132
Joined: Fri Oct 05, 2018 4:34 pm
Contact:

Re: New API Docs website

Post by Hornwitser »

I also want to hammer home that this site design (that's also shared with the main site, blog, mod portal and others) has the worst scroll lag I've ever experienced on a site with a mobile friendly layout on my mid range phone. I stopped reading FFFs on my phone because I'd rather not read the FFF than have to deal with the horrible scroll lag of the layout. The scrolling frequently dips below 1fps and it can take 10 seconds(!) from when I've scrolled down until it actually renders. No other mobile site I've ever accessed has been this bad.

Looking into the CSS, it's no wonder it's this bad:
box-shadow-stacks.png
box-shadow-stacks.png (28.44 KiB) Viewed 477 times
9 stacked blured box shadows, and that's just the panel inset. Add another 14 for the outset and 12 for the panel hole and it's no wonder this site design is the worst performing one I've ever seen. A single box shadow can measurably impact scrolling performance (2011) 35 layers of stacked blured box shadows is just madness. And the issue really is these box shadows because when I add * { box-shadow: none !important; } to the stylesheet all of the scroll lag vanishes like magic.

Please do what any sane person would do when implementing a tileset as visually intricate as the one you have and use border-images.
https://www.w3.org/TR/css-backgrounds-3/#border-images

robot256
Fast Inserter
Fast Inserter
Posts: 167
Joined: Sun Mar 17, 2019 1:52 am
Contact:

Re: New API Docs website

Post by robot256 »

My biggest complaint is how the return type of each function is forced onto a separate line from the name and arguments list, instead of all on the same line as in the old docs. Even more than waste horizontal and vertical space, it interrupts visual scanning of the column of names. Looking for a specific function name, the blue entries don't contain the same type of information (a type vs a name) and interrupt the alphabetical ordering.

mrvn
Smart Inserter
Smart Inserter
Posts: 4647
Joined: Mon Sep 05, 2016 9:10 am
Contact:

Re: New API Docs website

Post by mrvn »

Why is the content forced into a window roughly half the width of my browser? For some functions half the function arguments are cut off and there is no left/right scroll bar. And for most others the description is split into multiple lines. Meanwhile half the screen is empty.

Also the spacing between function prototype and description seems to be chaotic. Sometimes there is a large gap, sometimes a small gap. Visually it is unclear where the description starts because each line is different. A straight table layout so that all descriptions start at the same spot would be more readable. I would suggest 4 columns: function name, arguments, return type, comment. arguments and comment should line warped as needed.


If I make my browser window less wide it suddenly switches mode without "Classes" sidebar. There the comment is moved to the next line instead of after each prototype. Now suddenly the function arguments line warp as needed. That actually looks much neater. But then I scroll down to the methods section and the three lines for each parameter take a lot of vertical space. Even the two lines in the wide window mode seems wasteful on space. Argument name and type could be on the same line. Again a straight table layout would be more readable. Having the comments start at different offsets is odd.

Note: Frequently pages have a sidebar that can be collapsed. So it's one click to have the "Classes" sidebar visible or not. Let the user choose please.

PS: can i sort the functions of a Class in the overview at the top?

User avatar
Stringweasel
Inserter
Inserter
Posts: 40
Joined: Thu Apr 27, 2017 8:22 pm
Contact:

Re: New API Docs website

Post by Stringweasel »

mrvn wrote:
Mon Sep 13, 2021 8:46 pm
Why is the content forced into a window roughly half the width of my browser? For some functions half the function arguments are cut off and there is no left/right scroll bar. And for most others the description is split into multiple lines. Meanwhile half the screen is empty.
There's a button on the top right that expands the width to fill you screen. I found it after I had the same thought. :D

Gummiente27
Inserter
Inserter
Posts: 22
Joined: Mon Jul 16, 2018 2:59 am
Contact:

Re: New API Docs website

Post by Gummiente27 »

With these css rules the page looks much better to me, it removes the visual clutter inbetween the text:

Also this greatly reduces the amount of box-shadows, so it would further improve performance on older devices or browsers which are not good in handlng box-shadows.

Code: Select all

.panel-inset-lighter * {
    box-shadow: none !important;
}
.panel-hole {
    background: transparent !important;
}
If someone wants hr's horizontal dividers again, but simpler, try this css:

Code: Select all

hr {
    height: 1px;
    background: rgb(0,0,0) !important;
}
.dltabular hr {
    width: calc(100% + 64px) !important;
    background: linear-gradient(90deg, rgba(0,0,0,0) 2%, rgba(0,0,0,1) 5%, rgba(0,0,0,1) 95%, rgba(0,0,0,0) 98%) !important;
}
Before:Image
After: Image
After with hr's: Image

mrvn
Smart Inserter
Smart Inserter
Posts: 4647
Joined: Mon Sep 05, 2016 9:10 am
Contact:

Re: New API Docs website

Post by mrvn »

Stringweasel wrote:
Tue Sep 14, 2021 6:35 am
mrvn wrote:
Mon Sep 13, 2021 8:46 pm
Why is the content forced into a window roughly half the width of my browser? For some functions half the function arguments are cut off and there is no left/right scroll bar. And for most others the description is split into multiple lines. Meanwhile half the screen is empty.
There's a button on the top right that expands the width to fill you screen. I found it after I had the same thought. :D
Oh, it does that too? I tried that and it moved the return type into the same line as the function name. Didn't notice that is also uses all the space because when I tried I had the window already thin.

Do we need a tutorial for the API website?

curiosity
Long Handed Inserter
Long Handed Inserter
Posts: 81
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: New API Docs website

Post by curiosity »

I don't think the API website should need any tutorial. It must be simple and intuitive to use.

User avatar
eradicator
Smart Inserter
Smart Inserter
Posts: 5201
Joined: Tue Jul 12, 2016 9:03 am
Contact:

Re: New API Docs website

Post by eradicator »

curiosity wrote:
Wed Sep 15, 2021 10:25 am
I don't think the API website should need any tutorial. It must be simple and intuitive to use.
One might even go so far an argue that if the site feels like it needs a tutorial it's clearly overcomplicated. The old site's layout was quite straight forward.
Author of: Belt Planner, Hand Crank Generator, Screenshot Maker, /sudo and more.
Mod support languages: 日本語, Deutsch, English
My code in the post above is dedicated to the public domain under CC0.

Xorimuth
Filter Inserter
Filter Inserter
Posts: 329
Joined: Sat Mar 02, 2019 9:39 pm
Contact:

Re: New API Docs website

Post by Xorimuth »

Further to my earlier comments about monospace fonts, it would be useful if underscores had a gap between them to clearly show how many there are. Perhaps this is even more important for the wiki because of pages like https://wiki.factorio.com/Tutorial:Localisation.

Post Reply

Return to “Modding discussion”