We have been actively working behind the scenes to address your feedback regarding the design of API pages on the new Developer Hub. We appreciate the shared passion everyone has for API documentation, and we’re excited to hear your thoughts!
Today, we want to give our developer community the opportunity to provide us with feedback on the design changes we are currently working on. Please keep in mind that these designs are not yet finalized, and we have been listening very carefully to your thoughts and concerns in the original announcement thread.
The data that is shown may not accurately reflect the actual data we present on the site. What is presented here is just a design mockup for how we might present the data.
Check out these design images below and let us know what you think. If something isn’t shown here, we are open to ideas!
(Note: You may need to download these images to view them fully.)
Feel free to reply with your feedback below. Although we cannot promise that every critique of the design will be addressed, we will take your thoughts into consideration.
One important thing to point out here is that the data presented in the design mockups don’t necessarily reflect the data on the site, the purpose of these is to get a feel for how we want to present the data.
I like the changes a lot, my only complaint thus far (haven’t looked too much yet) is that the way inheritance is organized is still really bad. I remind you of my old suggestion: have the inherited methods/events work as a collapsed table, but with just as much information as if they were on their own page.
Argument types and moving type before name are much appreciated.
This is still way too bloated though. Listing for MaxForce is 22,000 square pixels on old design, and 410,000 on the new design. That’s almost 20x bigger, which is a lot of wasted space. I don’t want to have to hunt around a 3-page long document to find what I could identify with a quick glance previously.
Also, having multiple members on one line for inherited members is difficult to read. They should all be on their own line. They should have descriptions too. I shouldn’t have to visit the BasePart page to learn how to use methods of a Part.
I like design 1 better because all of the return types, names and arguments are inline. However I have seen some docs where they use design 2 which some people might prefer.
Still looks like we’ll have to click through to each inherited property, method and event just to get a description, but the inclusion of types and showing the inherited functions on the nav on the right is a big step up. The BodyVelocity page proposed is definitely the best so far, but not complete.
Things are starting to look a lot better. Functions being presented as signatures all on one line is so much more readable, and properties being presented with types in the same format is also great. Much prefer the second layout.
Not too keen on multiple methods being listed on the same line though. It’s not what my eyes expect so I tend to not pay attention to them and miss them.
Padding is also still thick and the side bars take up a lot of space that can’t be reclaimed.
Keep up the good work. Really appreciate seeing our feedback taken into consideration.
Thanks for mentioning this. Although we didn’t present this in a design context, we might change this to show inherited members without any collapse and with descriptions if you guys would prefer that.
In a sense, it is more compact. I sort of like how the inherited members are displayed as well. Some people may not like that though, so it would be nice to have a “collapse inherited” feature, where it displays the inherited members like in the first picture.
I prefer the alphabetical display of the classes from the first image, and the one-line display for the properties/functions/etc.of the second image. However, I still feel that a huge amount of space can be saved by heavily reducing the padding of the properties/functions/etc. Great improvement on the first iteration, keep it up!
An idea that I currently have in mind is to have two sort modes for classes: One that uses the class categorization scheme we have in place now, and one that displays classes in an inheritance tree like it was on the wiki. I’m not sure where class icons stand in this design currently, but we’ll work that out as we go.
