Sam Mohr (Dec 19 2024 at 01:15): Sam Mohr (Dec 19 2024 at 01:15):What I'm now expecting out of docs is a general structure for the comments:
There's a lot of stuff that's not documented, and a CI action like the panic reducing check that ensures we check that functions in the std lib are all documented.
More importantly (but also more difficult) is testing of doc examples a la Rust. It means that a doc reader and we the maintainers can have confidence that docs are at least syntactically correct, as well as understood to work as intended (unless they're transparently marked as not being tested).
The only GitHub issue I can find on this is on ensuring that the docs for builtins match the type of the documented builtin, meaning I don't think there's been work on this. We should get an issue together on this to make sure our "front door" is painted well.
Anthony Bullard (Dec 19 2024 at 01:16):And thanks to @Anton for his feedback as well as Richard for both his feedback and letting me take this on after complaining about one small issue with the old docs. That’s a lot of trust and I appreciate it
Sam Mohr (Dec 19 2024 at 01:17):This doesn't have anything to do with the doc styling, more just to say that the style of the docs have gotten good enough to slide way down to the bottom of the totem pole for "important stuff to fix on Roc documentation".
Richard Feldman (Dec 19 2024 at 01:17):it looks awesome, amazing work on it @Anthony Bullard - thank you so much!!! :heart_eyes:
Anthony Bullard (Dec 19 2024 at 01:17):Yes I think that is an important next step.
Luke Boswell (Dec 19 2024 at 01:20):I think we will need to wait for the next nightly, before the common man can re-generate docs for their packages... at least those of us who use @Hannes GH workflow :smiling_face:
Anthony Bullard (Dec 19 2024 at 01:21):Ok, I will love seeing these docs spreading across the land
Anthony Bullard (Dec 19 2024 at 01:22):I also will run lighthouse again on them from prod and take some notes on needed improvements
Anthony Bullard (Dec 19 2024 at 01:23):Would very much like to move the search items html into a separate doc and transclude it lazily
Sam Mohr (Dec 19 2024 at 01:25):Stylistic nitpicking suggestions on this:
Anthony Bullard (Dec 19 2024 at 01:42):Sam Mohr said:
Stylistic nitpicking suggestions on this:
- syntax highlighting of search bar results (probably that match the indentation of generated docs, because long function defs can be hard to parse when they text wrap)
- Different sections for types and values/functions
- Type annotation in a tooltip on hover for the sidebar items
- Allowing collapse of a module on the sidebar so I don't have to scroll so far to get to the next module after Num
- maybe a "sturdier" font? This one feels a little thin to me
None of these are hard, and I agree with all of them! The font was something I punted on but I think could help a lot!
lue (Dec 19 2024 at 01:43):other suggestions
Sam Mohr (Dec 19 2024 at 01:49):@lue that second suggestion is a godsend in the Rust docs!
lue (Dec 19 2024 at 02:14):Oh and the link for the current module name at the top of the main content brings you to https://www.roc-lang.org/ instead of the module-specific docs
Anthony Bullard (Dec 19 2024 at 02:15):lue said:
Oh and the link for the current module name at the top of the main content brings you to https://www.roc-lang.org/ instead of the module-specific docs
Interesting. Didn’t change anything about this. But it shall be fixed
Anthony Bullard (Dec 19 2024 at 02:16):I’ll compile a list of fixes / enhancements into a tracking issue after a couple of days feedback
Anthony Bullard (Dec 19 2024 at 02:16):I can put another week into this. But I also want to work on the compiler at some point :wink:
Hannes Carlsson (Dec 19 2024 at 09:45):suggestion:
The opposite case from one of lues suggestions; in a tall and too thin window, it'd be nice if the left navigation bar hides to show more of the content. see examples from other docs like ramda or rust docs.
Anthony Bullard (Dec 19 2024 at 12:03):@Hannes Carlsson Sounds like you want the mobile breakpoint to go up to something like 700px instead of only 480px (basically have mobile be mobile AND tablet)
Hannes Carlsson (Dec 19 2024 at 12:17):@Anthony Bullard yeah, I think that might do it. I'm not too familiar with frontends, though.
My specific usage is typically that I split my screen between editor, browser and terminal horizontally and the less space I need to give to the browser while still having it be readable the better
Anthony Bullard (Dec 19 2024 at 12:25):For sure
Anthony Bullard (Dec 19 2024 at 12:26):I think that makes sense
Anthony Bullard (Dec 19 2024 at 15:13):Need some Rust help to do the whole "have the type annotation be syntax highlighted" thing
Isaac Van Doren (Dec 19 2024 at 21:02):These look fantastic!!
Richard Feldman (Dec 19 2024 at 22:40):Anthony Bullard said:
Need some Rust help to do the whole "have the type annotation be syntax highlighted" thing
I have some ideas on syntax highlighting for the annotations in the headings specifically
Richard Feldman (Dec 19 2024 at 22:40):something I want to start doing is to have them become links
Richard Feldman (Dec 19 2024 at 22:41):I have a branch with progress on that
Anthony Bullard (Dec 20 2024 at 03:09):Could you share? Or do you want to finish it and work on other feedback?
Anthony Bullard (Dec 20 2024 at 03:26):I'll probably just defer to Richard for now and work on these much smaller items
Richard Feldman (Dec 20 2024 at 03:28):yeah I just need to land that branch, hoping to have some time over the next week to finish it up
lue (Dec 20 2024 at 10:40):Different sections for types and values/functions
Personally I love introducing types in the docs only once they become relevant/used (example). Big modules tend to have lots of types and introducing all of them upfront isn't helpful. Or did I misinterpret the suggestion or how docs are read/specified?
Anthony Bullard (Dec 20 2024 at 10:44):lue said:
Different sections for types and values/functions
Personally I love introducing types in the docs only once they become relevant/used (example). Big modules tend to have lots of types and introducing all of them upfront isn't helpful. Or did I misinterpret the suggestion or how docs are read/specified?
The idea here is for each module has its own sections for types and then functions. And usually a summary at the top
Anthony Bullard (Dec 20 2024 at 14:47):Here's a video showing some of the improvements that I was able to do this morning. Next up: Separating out Summary, Types, and Functions!
Anthony Bullard (Dec 20 2024 at 14:47):After I recorded this, I made a couple other _tiny_ tweaks
Anthony Bullard (Dec 20 2024 at 14:48):Screenshot 2024-12-20 at 8.48.06 AM.png
Got rid of that annoying border for the sub-entries extending oddly up, and aligned it _perfectly_ with the module name
Anthony Bullard (Dec 20 2024 at 14:51):And now works correctly at 200% zoom
Screenshot 2024-12-20 at 8.50.27 AM.png
And 400% zoom
Screenshot 2024-12-20 at 8.51.09 AM.png
Anton (Dec 20 2024 at 15:19):For all viewers: there is audio but it is very quiet
Anthony Bullard (Dec 20 2024 at 15:26):Oh really? Sorry, I need an editor :-)
Notification Bot (Dec 20 2024 at 15:38):38 messages were moved here from #announcements > New docs template is live ! by Anton.
Anton (Dec 20 2024 at 16:01):The zoom changes look great!
Anton (Dec 20 2024 at 16:03):I'm not sure about the collapse arrows. It seems like their usefulness does not offset the visual clutter they add. I quite like the changing background on hover, it makes the interactivity of the component clear as well as its boundaries.
Richard Feldman (Dec 20 2024 at 17:09):I don't have strong feelings either way about the hover, but I agree about the visual clutter on the arrows...what if we only showed the one arrow for the currently-opened module? that was the original motivating use case, after all!
Sam Mohr (Dec 20 2024 at 19:46):Loving the font!
Anthony Bullard (Dec 20 2024 at 20:06):I was thinking of only showing the arrows on hover, do you think that would assuage your concerns about the Noise @Anton ?
Richard Feldman (Dec 20 2024 at 20:12)::thinking: how would that work on touchscreens?
Anthony Bullard (Dec 20 2024 at 20:19):Of course not. The options there are to show them on mobile always, or just do what you said before and only have it for the current module
Anthony Bullard (Dec 20 2024 at 20:19):Which I think is fine, but might be surprising to many
Anthony Bullard (Dec 20 2024 at 20:19): Anthony Bullard (Dec 20 2024 at 20:20):That's what it looks like
Anthony Bullard (Dec 20 2024 at 20:20):What is your opinion on optimizing touchscreen usage of docs?
Richard Feldman (Dec 20 2024 at 20:21):hm, optimizing how?
Anthony Bullard (Dec 20 2024 at 20:21):I see some other docs that have collapsible section in the sidebar retain the affordance on mobile, but they are not sized appropriately for touch targets
Richard Feldman (Dec 20 2024 at 20:21):ah I see
Anthony Bullard (Dec 20 2024 at 20:21):What I mean is - do you think the touchscreen experience should be equivalent to the desktop
Richard Feldman (Dec 20 2024 at 20:22):not necessarily
Richard Feldman (Dec 20 2024 at 20:22):it's okay if some non-essential things don't work on touchscreens
Richard Feldman (Dec 20 2024 at 20:22):but yeah if we do have them, they should have appropriately sized hitboxes :big_smile:
Anthony Bullard (Dec 20 2024 at 20:22):I guess now we have to agree on whether or not this collapse functionality falls into that bucket :-)
Anthony Bullard (Dec 20 2024 at 20:22):I took pains to make them appropriately sized even on desktop
Richard Feldman (Dec 20 2024 at 20:23):out of curiosity, did you try having them left-aligned instead of right-aligned?
Anthony Bullard (Dec 20 2024 at 20:23):And that the text highlight happens on the thing that will trigger when clicked
Anthony Bullard (Dec 20 2024 at 20:23):I did not
Anthony Bullard (Dec 20 2024 at 20:23):But I can easily
Anthony Bullard (Dec 20 2024 at 20:23):Thank you flexbxo
Richard Feldman (Dec 20 2024 at 20:24):yeah I wonder if it might look less noisy if they're more like bullet points
Richard Feldman (Dec 20 2024 at 20:24):maybe with lower opacity as well?
Anthony Bullard (Dec 20 2024 at 20:43):Here you go!
Anthony Bullard (Dec 20 2024 at 20:44):And Anton had complained about the "fat"(2px) borders, especially here:
Screenshot 2024-12-20 at 2.43.01 PM.png
Here's a version with 1px borders
Screenshot 2024-12-20 at 2.42.38 PM.png
And a version with 2px border only on the left
Screenshot 2024-12-20 at 2.42.18 PM.png
Anthony Bullard (Dec 20 2024 at 21:05):Screenshot 2024-12-20 at 3.05.12 PM.png
Here's a preview of the v3 sidebar if you don't want to open the video
Luke Boswell (Dec 20 2024 at 21:12):Ticks on the left is a nice improvement I think.
Anthony Bullard (Dec 20 2024 at 22:50):What do we think as a stand-in for Richard's solution? This ended up being easy than I was making it...
Screenshot 2024-12-20 at 4.49.44 PM.png
Anthony Bullard (Dec 20 2024 at 22:50):I'll probably have to adjust the colors in there
Anthony Bullard (Dec 20 2024 at 23:02):One option for the a11y portion is to just lower the luminance of the violet background color to 15%, just like the code background - which avoids some of the washed-out colors when we raise luminance too much in the syntax highlighting pallete
Screenshot 2024-12-20 at 5.00.56 PM.png
Anthony Bullard (Dec 20 2024 at 23:04):I think it's pretty metal with the left-only border (slightly fatter) on the entry names...
Screenshot 2024-12-20 at 5.03.41 PM.png
Anthony Bullard (Dec 20 2024 at 23:16):Sorry I had some time after an early day of work and before christmas break
Luke Boswell (Dec 21 2024 at 00:17):I like the look of that last one.
Richard Feldman (Dec 21 2024 at 00:23):I don't have any strong preferences among these, so happy to defer to others' preferences!
Anthony Bullard (Dec 21 2024 at 14:37):Seems like the last design has a good number of fans
Anthony Bullard (Dec 21 2024 at 14:38):I have that work completed locally
Anthony Bullard (Dec 21 2024 at 14:38):I think I'll push that up this morning, and then take on the signature tooltips
Anthony Bullard (Dec 21 2024 at 14:55):I'll hide this so you don't get flashbanged, but this is the light theme of the same:
Light theme
Anthony Bullard (Dec 21 2024 at 14:56):I personally don't love it, but I really don't like light theme in general, so I don't really know how those who do would improve it.
Anton (Dec 21 2024 at 15:13):Some good suggestions from Claude for the light theme:
- The search bar could be more prominent and styled consistently with the purple theme
- The "(press $)" hint looks like a placeholder - this should be integrated more elegantly, perhaps as an icon or keyboard shortcut tooltip
The syntax highlighting colors could be improved (those for the dark theme are really good).
The purple background color for the sidebar does not look great. A white sidebar could be an option but that change alone would probably not look good yet.
Anton (Dec 21 2024 at 15:14):The search bar would probably look better without rounded corners, making it consistent with the rest
Anthony Bullard (Dec 21 2024 at 15:15):Yeah, I think I'd like to punt on light theme for this PR, but here's what a square search input looks like:
Screenshot 2024-12-21 at 9.15.23 AM.png
Anton (Dec 21 2024 at 15:18):Uhu, it needs some additional changes, it's probably not too difficult to find a bunch of inspiration for search bars
Anton (Dec 21 2024 at 15:18):But yeah, not needed for this PR
Luke Boswell (Dec 21 2024 at 19:06):For light... I think it would be good to switch the darker color in the sidebar and the lighter behind the logo/header
Anton (Dec 21 2024 at 19:16):Yeah, I've also seen a light theme with a relatively dark sidebar in protonmail
Luke Boswell (Dec 21 2024 at 19:25):Also the dark purple on the scrollbar and the LH side of the boxes feels very bright and draws attention. That feels a little wrong as they're not important visual elements.
Anthony Bullard (Dec 22 2024 at 01:26):What about this @Luke Boswell @Anton . I have seen a lot of "bare white" designs for light mode that seem to work well.
Screenshot 2024-12-21 at 7.25.35 PM.png
Luke Boswell (Dec 22 2024 at 01:45):I like it... though now the border around the types is intense... maybe just a light background with a LH side border like the dark mode?
Luke Boswell (Dec 22 2024 at 01:46):I think all that needs to change is just the border on the LH side only
Luke Boswell (Dec 22 2024 at 01:46):And maybe the border on the search box... not sure but is that a different color?
Sam Mohr (Dec 22 2024 at 01:47):To extend what Luke is saying and also what he said a few messages ago, I think we should have a 3-step scale from white to light-violet/purple: the main panel should be white, then the sidebar should be a very light purple, then the logo rectangle in the top-left should be a darker purple
Luke Boswell (Dec 22 2024 at 01:47):I like the round corners.
I think just a light violet for the search border is nice. Similar to dark mode. It just chills there and doesnt stand out too much
Sam Mohr (Dec 22 2024 at 01:48):If the top-left corner is lighter than the sidebar as it is in the last demo, it makes the website feel "off-balance"
Anthony Bullard (Dec 22 2024 at 01:49):That's not going to be there (Meant to be a reply)
Sam Mohr (Dec 22 2024 at 01:49):What's not gonna be there?
Anthony Bullard (Dec 22 2024 at 01:49):Sam Mohr said:
To extend what Luke is saying and also what he said a few messages ago, I think we should have a 3-step scale from white to light-violet/purple: the main panel should be white, then the sidebar should be a very light purple, then the logo rectangle in the top-left should be a darker purple
I tried this and it looked _terrible_
Anthony Bullard (Dec 22 2024 at 01:50):Luke Boswell said:
I like it... though now the border around the types is intense... maybe just a light background with a LH side border like the dark mode?
That's not going to be there
Anthony Bullard (Dec 22 2024 at 01:51):I'll try a different version of what you suggested later Sam
Anthony Bullard (Dec 22 2024 at 01:51):Right now I'm fighting with strange formatter code
Sam Mohr (Dec 22 2024 at 01:51):Thanks!
Anton (Dec 23 2024 at 13:07):I have seen a lot of "bare white" designs for light mode that seem to work well.
That sidebar looks great :)
Last updated: Jul 06 2025 at 12:14 UTC
