I get that the newer one has lots more information, but it seems really unnecessary, clutters the page, and because of that it takes more time to get to the properties, functions, etc. It also doesn’t help that the font size is much larger.
The very first sentence “The UserInputService is a service used to detect the type of input available on a user’s device via the use of a LocalScript.” and “The primary purpose of this service is to allow for games to cooperate with multiple forms of available input - such as gamepads, touch screens, and keyboards.” are the only things that really need to be there.
The functions and events on the new wiki also really annoy me:
The newer page seems to have missed a memo that you should include the parameters of a funtion on the page.
I really like the style of the new wiki, but it’s severely lacking in a lot of places.
We hear you loud and clear
In the design images we posted above, we do have function arguments listed now.
As for the longer descriptions, we want our documentation to be rich and descriptive. Experienced developers may only need a sentence or two, sure, but new developers won’t understand how these classes work out of the box, so its important that we give them as much useful information as we can.
Key issue behind both designs (in my eyes) is that tables are used for non-tabular things. The gray header/top row of those tables and the table its lines grab a lot of attention and disorient me from the page structure itself.
The first design has a lot of redundant labels in my opinion; the C-style signature is much clearer and natural to me. Maybe for programmers unfamiliar with such function signatures the first style is more clear though(?).
Personally I really like this style (i.e., without tables):
Small section header:returntype funcname(argtype1 name, ...) ~~~~~~ (right align) ~~~~~~ [inherited from XYZ] [plugins only] […]
Section body: description…
I’d also love it if the inherited stuff was actually fully expanded and the class hierarchy of the currently shown class was more clearly shown.
I do like the new styling though (class categories are great, search works better (but still prioritizes arbitrary class members over the class itself?), looks good), but these are the primary issues I still have with the API pages.
I like the right-most image (ClassFeedback.png) a bit more namely for each function being separate. I feel like that design would work better if, similarly to the old wiki, the boxes to hold the text and information were a lot smaller. I really liked the column idea on the original wiki, where the properties, functions, and events were put on the left, and their explanation on the right. I feel like this could be achieved if we had a sort of drop-down menu for each of the things on the page.
I strongly prefer a compact view in a more direct sense. I prefer it because I don’t have to go over such a large area to find something, but rather I could easily identify the category (On that note, the bold category titles are dwarfed by the size of the information boxes, which is the opposite of what should be going on), skim the list of items below to easily view the name and information of an attribute in one single sweep, and move on. The box idea doesn’t really allow for such a fluid search as it breaks the steps of searching up into definite pieces. Of course, this may be very beneficial for users who are just starting out, since it’s great to start slow, but I think it’s a hindrance to someone like myself who has known Roblox’s API for so long and just wants to do a quick skim to check knowledge or find something.
I still feel like this redesign is settling for second best when it comes to readability. The vertical padding between elements is bordering on absurd for a page that’s supposed to be quick, compact, and easy to navigate. I could glance at a page on the old layout and almost always find the information I needed, now I have to scroll up and down searching for information that’s significantly more spread across the page than before. Readability and efficiency are king for an API page and I don’t feel like the new design improves on the old design in either of these areas.
I think we should at least have some vertical padding between members. We definitely need to trim the padding down a bit from what is currently in the design, but what’s on the wiki right now feels really extreme.
I feel like one of the issues with the new version is due to either the font size or the line spacing. All of the descriptions feel like they have double line spacing, which causes an unnecessary amount of white space. Additionally, the font size seems much larger.
Compare this to the old version where the line spacing was minimal and each description could fit more than 5-6 words on a line.
Being able to simply find the member itself in an efficient manner trumps a fancy looking description section. The old layout lets me find the member quickly and from there I can glance over at the description if need be. I’d also argue that the descriptions should be kept to a minimum length to save on space, they can be expounded upon on their own page.
The almost indiscernible row shading doesn’t help alleviate the squished descriptions on the old page, but I still prefer it to scrolling endlessly.
No worries, we totally agree. We actually have a summary field specifically for this purpose so that we only need to describe members with 1-2 sentences on the class pages.
As for quickly finding members, is there anything wrong with having a table of contents on the right hand side to quickly go to what you’re looking for?
Curious, on the old wiki would you read through the whole list of members or would you just ctrl+f to what you were looking for? This is what I always do
It’ll certainly help, it’s not as easy as having almost everything right in front of you to begin with but I can certainly reteach myself to navigate using that to maximize efficiency.
That seems like a fair compromise then. We’ll try to trim down on the padding between members so its not as spaced out, but the table of contents widget should help strike a balance between easy navigation and having a rational amount of padding between descriptions.
Scan the whole list of members. Broadphase was Property/Method/Event, narrowphase was looking over ~10 items in a list to find what I want. Using the keyboard to open Ctrl+F and then typing a member name (which I may not even know) would be slower.
The information density on the new developer hub is incredibly low, and if I want to reduce the page zoom so more information can fit in the screen, please let me do it! Don’t restrict my screen space - that’s basically killing the purpose of zoom.
The low density is due to the padding: it is very large, and is on everything. Having to scroll 10 pages down for something that would be just one screen down on the old wiki is very counterintuitive.
5 results are on-screen for the old search, and 5 results are on-screen with the new search. There is something off with the new search though which is what you may be seeing. On the old search, the descriptions contrasted really well with the link to the result’s page. For the new search, they blend in together – the links seem like regular section headers, so I have to strain my eyes to look through the results.
Please show what the class extends from on the same page!
(For reference, see official javadocs. They clearly list what inherits from what, and it is really helpful to find out what things work in a similar fashion)
Also, I find myself agreeing with everyone else when it comes to the massive amount of whitespace on the page. I’d much rather have less whitespace but more functions in the same space, rather than to have to scroll down to search for what I am looking for.
Overall though, I am looking forward to the redesign!
