Documentation Site Updates Roundup

Hi Creators,

Over the past few months, we’ve been improving our documentation site to make our resources about Roblox development easier to find and use. Thank you to those who’ve reported bugs and given us feedback!

TLDR: We’ve updated the look and feel of the Engine API reference page to make these resources easier to read and navigate, especially on mobile devices. We added some missing content like code samples and API tags throughout our documentation, and implemented semantic search to make it easier to find resources like guides. We also made our docs more accessible and easier on the eyes, added better interfaces for documenting explanations, and more!

Read on for details about these changes:

Design & Accessibility

  • APIs were hard to navigate to or search within nested UIs. We made formerly hidden or collapsed content visible, flattened the information layout to make it searchable, added helpful tooltips with definitions over API types and terms, and improved our site’s styles to make them easier to read (see Figure A below)
  • Redesigned Engine API pages with a simplified, easily searchable interface, featuring helpful tooltips on return types
  • Improved responsive design for mobile throughout
  • Implemented responsive design and better styling for Engine enum pages
  • Added keyboard navigation and enhanced our design for accessibility. You can now navigate documentation using arrow keys, and initiate a search through a keyboard shortcut: Ctrl/Cmd+K and Ctrl/Cmd+Spacebar to search docs (see Figure B below)
  • Added better highlighting for Luau syntax including string interpolation, built-ins, and library keywords. Also fixed the syntax highlighting for C# code samples (see Figure C below)
  • Added our new font throughout the site and adjusted spacing for documentation to make it easier to read
  • Addressed inconsistencies that the documentation site had with the rest of create.roblox.com, including the look and feel of the sidebar, scrollbar, spacing, and layout

image1

Figure A: Easy to navigate API summaries with useful explanations exposed through tooltips


image4
Figure B: Full keyboard navigation of docs and docs search (Ctrl+ K or Spacebar)


Figure C: Improved syntax highlighting


Figure D: Color swatches to document colors

Content & Tags

  • Added New Color swatches to pages like BrickColor for documenting colors better (see Figure D above)
  • Open Cloud docs now show additional documentation on all possible resource paths and document code samples more accurately
  • Added missing page links and descriptions to certain types
  • Fixed deprecated APIs that were appearing when they should have been hidden
  • Engine APIs are now more accurately tagged as deprecated or with certain security tags
  • Engine enum pages now expose tags, such as Deprecated and more
  • Certain Engine APIs now have more accurate types surfaced in the documentation
  • Missing code samples on certain API pages are back

Internationalization

  • Engine API pages are better translated per language
  • Fixed Documentation menu that was not showing for users of some languages
  • More translations of the Documentation site are available across languages

Search & Assistant

  • Enhanced Search to fetch articles beyond API references from Roblox docs
  • Updated Assistant spacing and font to make conversations easier to read
  • Docs search now has some semantic understanding and can rank guides higher than API pages. (See Figure E below)
  • We’re continuously working on optimizing the Assistant with better responses to your questions

Figure E: Semantic search (right side of image) results in more relevant results when searching for “how to code” compared to previous search (left side of image)

We hope these updates make our documentation more accessible, more accurate and complete, and easier to use. Let us know if you have any feedback about these updates, and stay tuned for some upcoming news around better internationalization for Roblox Docs!

Thanks,
The Documentation team

172 Likes

This topic was automatically opened after 9 minutes.

This feels and looks overall so much better! It was quite difficult finding what I needed as the docs eventually got bigger and bigger

28 Likes

Did a great job on it. But please please please sync the notifications it is so annoying opening a notification on 1 section then on every other section that cursed blue dot is still there

17 Likes

I think what would be good is a dedicated search category for API reference, a lot of the time I search up API terms only to be met with guides, even when using the exact keyword or name of the API.

16 Likes

i wonder if we’ll get more documentation for gc stuff, i don’t really want to go looking through the luau source code to see how it works and i don’t really think anyone fully understands it besides roblox themselves

(sorry i don’t know how to merge these properly and i didn’t quote enough)
i agree, searching up simply “workspace” comes up with the workspace global instead of the service itself which is never useful

13 Likes

I do not know how to emphasize to Roblox how much I do not want my doc site to have an AI assistant in it.

Generative AI is set to revolutionize the world but unless you can promise me that it isn’t hallucinating information, I can’t trust it, which means I have to double check what it says anyway. I’d much rather the focus be on improving other parts of the doc site. There is still no way to visualize Instance inheritance, as an example, despite it being a very powerful part of Roblox’s API.

You can take a look at a site like Roblox API Reference for a good idea of what I want out of a reference. Quick to navigate, has all the relevant information, and no fluff.

27 Likes

Thank you so much for all of the works that has been done to make the docs user friendly!!

I do have one request though, which is to either have an alias url like docs.roblox.com, or a docs search bar on the landing page of create.roblox.com because oftentimes when i need to reference the docs i would type in cr and let the url bar complete the rest, but that page does not have the search bar so I always have to move my mouse to Documentation tab then click on one of the dropdown menu which is kind of inconvenient when I need to use the docs a lot.

11 Likes

If only I’d not have to fork that many GB.

7 Likes

The documentation still redirects to the wrong language.

10 Likes

Any effort to make the Plugin:OpenWikiPage() function work again, or edit it’s documentation to make it clear how to use it if it does still work?

12 Likes

I just had to

10 Likes

Dark mode is juice to my eyes, also it was really confusing the whole dev section

8 Likes

Keep improving! Thank you for trying to make the documentation better!

7 Likes

better than previous navigation.

8 Likes

When Editable Mesh will be enabled on client?

8 Likes

Little late here, however everyone who worked on this did a great job! This is really useful.

4 Likes

Hi @MonkeyFollicle can you explain steps to reproduce the issue you are seeing?

We will be removing the dropdown soon to make it fewer steps to get to Documentation. I’ll also float your idea of a URL alias to the team.

1 Like

Hi @Dekkonot we are actively working on a few initiatives to resolve your concerns. Stay tuned for a better way to visualize Instance inheritance, too!

1 Like