All of my complaints about the new documentation site

I was very excited to learn that a new documentation site has been in the works, and very disappointed to learn that it makes nearly all the mistakes the old one did. Some things are better, such as dark mode. Some things are worse, such as class sorting. Overall I am not a single inch closer to using first-party documentation in my workflow. Here is a list of my complaints upon initial inspection.

  • Class list is alphabetically sorted. This is not useful. Alphabetical sorts are for when you need to find a specific item on a list. If I’m looking for a specific item, I just search it and never land on this page. This page should be a tree view of the class hierarchy. Same for the sidebar version.

  • Table of contents on instance pages is absolutely colossal, pushes all the useful content entirely off the page if it doesn’t fit side by side. Documentation is often used with only half the screen so the developer can reference it while they work. This has to work at half-width and less.

  • Every instance page has every superclass member pasted onto the page in its entirety. This is a complete waste of space. I’m of the mind that you don’t need superclass members on the page at all. At the very least they should be hidden by default.

  • Headers are colossal and can’t be collapsed. I should be able to see the documentation for FireServer and OnServerEvent on the same page without scrolling so that I can read it while I work.

  • There is no link to a class’s superclass on the class page.

  • Inline monospace blocks are too hard to read. They are way too tight against the text, difficult to see the shapes of letters. Also there is no spacing between blocks when they’re back to back - such as in the instance member lists.

  • WAY too much whitespace. Compare:


    Almost 2/3rds of my screen is being used for nothing and that’s not even counting the completely vacant sidebar. Documentation needs to be functional and any design goals need to take a backseat to usability. This alone would stop me from ever using this site, just as it did with the devhub.

  • Instance page content is lazy loaded as you scroll. It is basically impossible to just scroll down to a member. You have to scroll up and use the table of contents so that your scroll position gets anchored, and then you aren’t allowed to scroll at all for several seconds because every time anything loads it resets your scroll to the item you clicked. Annoying solution to a fabricated problem.

  • Backward navigation makes no sense. If you go to the accessory page, your navigation buttons will be API Reference (ok), Classes (ok), Avatar (does not make sense and also is not even a button), not the Instance superclass (as one would expect), and then Accessory. There are many such classes.
    image

  • Instance methods and events don’t list their parameters in their header.

  • There is no information on an object’s subclasses. If you see this cool Light object and want to make it, you have to just know all of its subclasses and what each of them is for.

  • Most of the handwritten documentation is just copy and pasted from the current wiki, so many classes such as OutfitPages are still completely undocumented.

  • The BrickColor page doesn’t show the colors on the page. Bug?

  • Auto documentation completely fails at certain points.

  • Methods that return a Tuple or a Dictionary are still totally undocumented


  • Function return values are almost always unnamed
    image

  • Can’t search for class members. Major regression from the previous wiki.

  • Sidebar does not scroll with the page. Need to scroll back up to reach site navigation.

  • Enums don’t link back to items that use them.

  • Declared types are internal types instead of luau types. “int64” should read “number”. “bool” should read “boolean”. etc.

  • Instance/property/method/event icons are nowhere to be seen.

  • There is no version history information (when was an item added? when was a page updated? etc)

  • Data types are missing from documentation: BinaryString, Font, RotationCurveKey

  • There is no search hotkey

In summary, I don’t see the purpose of this site. No lessons were learned from the previous iteration or from adjacent products like MDN, Unreal Engine Documentation, or Unity Documentation. I am no closer to switching my documentation source than I was yesterday.

This is a link the original thread to ensure @peraldon gets notified.

42 Likes

Just want to add my own complaints about how broken the new documentation site is on mobile:

5 Likes

Then what documentation were you using??

Other than that, yeah, I kinda agree with the stuff brought up here, but it’s still in beta ¯\_(ツ)_/¯
Though, why didn’t you reply to the main thread?

Anaminus’s documentation: Roblox API Reference

2 Likes

I mean, in all fairness at least it’s in dark mode. As someone who NightDevs a lot, I hate having to use the old devhub page at 01:00 and have my eyes burnt because I was wanting to double check how string.sub() works.

Anything dark mode > Anything light mode

2 Likes

If it ain’t broken, they’ll fix it 'til it’s broken again.

4 Likes

Why are you putting your complaints here? They’ll only be seen if you put them under the original announcement.

1 Like

That’s not true + I linked this thread.

1 Like

When I replied to this it was under #development-discussion. Regardless, it’s probably better to respond to the original announcement thread. That’s where the specific product team is going to be most actively looking.

2 Likes

Hey!

Thanks for taking the time to write all of this up, really appreciate it. I won’t respond to each of them individually, because there are quite a few disparate ones. Overall though, we released this as an early Beta explicitly to get user feedback like this, so we can build a product that’s more closely shaped by the Creators who use it.

Needless to say, this thread spawned a good few line items for investigation, and hopefully, you can start to see some of the things you brought up appear as we continue to polish and improve the site.

Thanks!

10 Likes