Stream: contributing

Topic: Order of docs?

itmuckel (Mar 27 2023 at 19:49):

Hi, I'm still trying to figure out how to do the first day of AoC in roc :-D I'm having a hard time navigating the Docs, because they don't seem to have an order, like the list functions:

isEmpty
get
replace
set
append
prepend
len
withCapacity
reserve
releaseExcessCapacity
concat
last

at first I thought there was no head or first, but it's much further down, not next to last, so I missed it and searched for head, but then found it. Is there a reason for this or does the generator just take the functions in the order it finds them in the code? Shouldn't it be sorted alphabetically?

Anton (Mar 28 2023 at 08:43):

Thanks for bringing this to our attention @itmuckel, they are indeed in the same order as in the code.
I've checked some other languages and alphabetical order is indeed the norm, I'll make an issue for that.

Anton (Mar 28 2023 at 08:47):

Our "search bar" should also be much larger and centered. So it stands out, looks familiar and is easier to reach from more mouse positions on the screen.

Anton (Mar 28 2023 at 08:49):

I have not seen this with other languages but I also think the search bar should be "fixed"; it should still be visible as you scroll down the page.

Anton (Mar 28 2023 at 08:53):

We've talked about it before but I think we should experiment with how we can nicely show synonym function names (show keepIf when filter is searched). The different names table is simple but not delightful. Less clicks is better.

Anton (Mar 28 2023 at 08:56):

I welcome any objections against these proposals

Luke Boswell (Mar 28 2023 at 09:47):

We could potentially have a list of common function names and add it to the end of the search box, so when you search for something it appears below the modules and links to the Roc equivalent function.

I really like how the docs look now, but i sometimes find them difficult to use. Navigation is the main issue I have. I like the idea of the search bar floating as the users scrolls down the page that might encourage its use for people who hadn't noticed it.

One thing I've wanted it an index or Table of Contents for all of the builtins, so I can see them all listed out and link to them. I find I am clicking between different modules, just to see what is in there.

Another idea, could we layout the list of modules and sub list of function differently? Maybe horizontally in a bar for the modules, and then functions are expanded beneath it? It would be a more compact presentation of the information, like columns in a table.

Maybe we could add keyboard navigation, left-right or up-down might slide between different functions or modules. Like having a single function/type centered and focusses and there is a preview of the next card/function to navigate to in a direction.

Maybe we can merge all the functions from multiple modules (or even packages) into one gigantic indexed list, and then use other features to sort and filter them. Sort them alphabetically, by input or output type, or by module, or name contains, contains type, or most frequently used.

Maybe we could identify the different ways people use the docs and really focus on that for UX. Just some random thoughts...

• People looking for a specific function they already know about? - optimise for Search Bar
• People wanting to browse for a general overview/learning/thinking? - provide an index, and then optimise for scrolling through the functions in a module, and switching between modules
• People want to find a similar function that does a thing? - can we have a search that understands types, like I'm looking for a List a -> List a or something. What about filtering etc.

Just some random ideas.

Anton (Mar 28 2023 at 10:07):

Some good ideas, but I think it's important to not go overboard with the number of features, simplicity has so many benefits. I also believe LLMs like chatGPT will soon be the preferred way to get docs information so I would optimize mostly for that use case.

Anton (Mar 28 2023 at 11:09):

I also believe LLMs like chatGPT will soon be the preferred way to get docs information so I would optimize mostly for that use case.

Do you have any specific doubts about this @Richard Feldman?
My reasoning is that we will increasingly use "description of intent" to generate code and that LLMs will soon be capable of interacting with the docs API through plugins.

Richard Feldman (Mar 28 2023 at 11:33):

I don't have any specific doubts about it, but I'm not sure what the implications would be for the docs site layout :big_smile:

Anton (Mar 28 2023 at 11:44):

For me, the implications would be to prioritize a good docs API over a small improvement in UX of the docs website

Richard Feldman (Mar 28 2023 at 11:49):

hm, but wouldn't an LLM do about as well as long as it's aware of all the content, kinda regardless of how it's organized?

Richard Feldman (Mar 28 2023 at 12:00):

Anton said:

Our "search bar" should also be much larger and centered. So it stands out, looks familiar and is easier to reach from more mouse positions on the screen.

my thinking was that in the future we'd want a separate search bar across the top to search for packages. some options:

• we could not do that, and have a different way to search for packages
• we could have the search bar across the top search both for packages as well as within the current package. I think seeing the search results for both packages as well as the current package together would feel weird, but I could be wrong.

dank (Mar 28 2023 at 12:06):

roogle when
\s

Anton (Mar 28 2023 at 12:25):

hm, but wouldn't an LLM do about as well as long as it's aware of all the content, kinda regardless of how it's organized?

There are some distinctions here:

• I believe none of the popular LLMs are using images of websites to look at them like humans see them, so CSS does not matter at this point.
• To ingest the text of the docs during the training phase, the structure of the text matters. From my understanding, having good, clean, semantically logical HTML is beneficial.
• The API that is accessible to ChatGPT through its plugin system, with which it will interact while not being explicitly trained on the use of for example a roc docs plugin.
• The HTML of the page will also matter for use with the ChatGPT browser plugin but I have not looked into that yet.

Richard Feldman (Mar 28 2023 at 12:30):

right, so I think we're doing well on the semantic structure of the HTML already...I hadn't really thought about a docs API

Richard Feldman (Mar 28 2023 at 12:31):

one thing that comes to mind is that it's free, minimal-latency, and HN-proof (no fear of the Hacker News "hug of death" that takes down the server) to host all the docs as static HTML content, whereas if we offered API access to the docs, we'd need non-static servers to host them

Anton (Mar 28 2023 at 12:38):

I see... I'm going to think about that for a bit :)

Anton (Mar 28 2023 at 12:50):

my thinking was that in the future we'd want a separate search bar across the top to search for packages. some options:

Rust docs website have a smaller less noticeable search bar for crates above the "this crate search bar". We could do it like that, but I've never used that crates search bar before on a docs website and did not know it existed before today :p

itmuckel (Mar 28 2023 at 17:15):

ChatGPT? LLM? (Whatever that is) I would actually be happy with sorted functions and maybe a more prominent search box, because I didn't even know it was there. :-D

Anton (Mar 28 2023 at 17:20):

Yeah, we got distracted :p but I did make issues #5219 and #5220 for your concerns :)

itmuckel (Mar 28 2023 at 17:22):

Now I know why I missed the search bar, it doesn't even look like one. :smiling_face_with_tear:
grafik.png

Anton (Mar 28 2023 at 17:23):

True, it's good that you brought it up!

Anton (Mar 28 2023 at 17:27):

To continue the conversation about the docs API, I suggest we wait until we have access to the ChatGPT browser plugin so we can see how well it does with our current docs website. I found that the browser plugin uses bing and bing actually found our docs website with the search query "roc builtin docs list" so that's a good sign!

Anton (Mar 28 2023 at 17:32):

I was looking at instruction videos about the ChatGPT plugins and found an accidental? google home page :big_smile: :
accidental_google.png

itmuckel (Mar 28 2023 at 17:36):

Another thing that could use its own thread, but what annoys me since I first saw the website is that there's no way from the homepage to the docs or tutorial or anything else, I mean the header is missing from the start page. When I want the docs I can't go to roc-lang.org, because I know I won't be able to navigate from there. So I always go through github and the links there. And if I accidentally click a link to the homepage I need to go back by browser-back, because there's no link back to the tutorial or docs. Should it stay this way? :sweat_smile:

Anton (Mar 28 2023 at 17:41):

The header should definitely be there before we release roc 0.1, what do you think about adding it now @Richard Feldman?

Richard Feldman (Mar 28 2023 at 23:21):

seems reasonable to me!

Richard Feldman (Mar 28 2023 at 23:21):

https://www.roc-lang.org/tutorial has a header, and the docs should too

Richard Feldman (Mar 28 2023 at 23:22):

if anyone wants to do that, happy to accept a PR for it!

Richard Feldman (Mar 28 2023 at 23:29):

the homepage shouldn't have it yet though

itmuckel (Mar 29 2023 at 06:20):

Shouldn't it at least have links to the tutorial or docs or both? A few weeks ago I told a coworker about roc, and he googled it, landed on the homepage, was looking for code examples, scrolled through the page and I told him "no, you have to go to the github repository and click on the tutorial", which is rather unfortunate :-/

Richard Feldman (Mar 29 2023 at 12:49):

there's a link to the tutorial on roc-lang.org, you just have to read through a couple of paragraphs

Richard Feldman (Mar 29 2023 at 12:49):

part of the reason for this design is wanting to set a somewhat high bar for patience

Richard Feldman (Mar 29 2023 at 12:50):

the idea is that if someone doesn't have enough patience to read through a couple of unstyled paragraphs, they'd be quite likely to get frustrated with the immaturity, compiler bugs, etc. - and then leave after having a negative experience

Richard Feldman (Mar 29 2023 at 12:50):

so better for everyone if they conclude "this isn't ready yet" before actually having a negative experience

Richard Feldman (Mar 29 2023 at 12:51):

whereas if someone makes it through that homepage experience and says "yeah I want to give this a try anyway, despite it being in this unfinished state" then their expectations have been calibrated appropriately for where the implementation of the language currently is

Richard Feldman (Mar 29 2023 at 12:52):

the original website was even more bare-bones than this, to emphasize that even more (because the language was even more immature then)

Richard Feldman (Mar 29 2023 at 12:52):

so the idea is to make the homepage more polished as the language itself becomes more polished

Richard Feldman (Mar 29 2023 at 12:53):

I do think pretty soon (like in the next couple of months) we'll want to update the homepage to look more styled and have a nav bar and such, but before we do that I'd like to have the other pages updated

Richard Feldman (Mar 29 2023 at 12:54):

so that when people follow the links from the homepage, they don't suddenly get a worse experience than the homepage's level of polish would suggest they'd get :big_smile:

itmuckel (Mar 29 2023 at 13:20):

Oh, thanks, I missed the tutorial link :D

Last updated: Jul 06 2025 at 12:14 UTC