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.
-
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
-
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.