Georges Boris (Apr 24 2023 at 11:45): Georges Boris (Apr 24 2023 at 11:45):Hey folks, I'm working on something for the Elm ecosystem and I wanted to do the same for the Roc ecosystem. I wanted to know your thoughts. If it makes sense, if it would be better to not mix these efforts (especially since there is Elm code involved for sure).
I have this library called elm-book, you can think of it kinda like a mix of hexdocs (erlang ecosystem) and storybook.
For v2 I'm working on making it a lot more flexible, so you can both create custom stuff but also auto-generate it based on your package docs.
The result is a mix of the two so you can have your docs, guides, interactive examples, etc. all living in one place.
I'm also working in something more ambitious, which is packages.elm-book.com. Which should be a mirror of all packages from elm packages but with auto-generated elm-books. By default they will just have the same things we have on the official packages but by providing some config on your repo we can also enrich it in various ways... I'm hoping to also enrich the search experience of the packages website.
I know Roc, with it's custom editor, has the possibility of having something really especial. However, I'd love to help with the docs experience so that Roc ecosystem can have something as rich as Erlang packages have "by default". Basically every elixir package has an at least decent documentation website, that can be customized to "feel" like they are something unique and also enriched so they have more than just function definitions but also structured guides etc. With elm-book we may have something like this but that could also provide interactive environments, etc.
Initially, I'd try to just use the same setup but reading from other sources so we could have Roc packages enriched using Elm/etc. But as soon as we have a more established frontend platform, I'd love to maintain compatibility with that as well so you could create your interactive stuff, define themes, etc. using 100% Roc.
Finally, I don't think that would conflict with Roc's goals for in-editor documentation in any way since the idea would be to use the default docs as an input source. So no changes necessary there at all.
That's it! I just wanted to hear your thoughts. If you think that it would be better to just separate these two projects entirely, that is fine as well. :) But I'm keen on providing the best I can for both ecosystems.
Anton (Apr 24 2023 at 12:12):I'd love to help with the docs experience so that Roc ecosystem can have something as rich as Erlang packages have "by default".
This a goal for sure :)
Basically every elixir package has an at least decent documentation website, that can be customized to "feel" like they are something unique and also enriched so they have more than just function definitions but also structured guides etc.
Love this too!
I am wondering if the added complexity of introducing elm is worth it, especially since we plan on transitioning to 100% roc in the long term. What do you think @Luke Boswell?
Georges Boris (Apr 24 2023 at 12:14):Btw - I'm mentioning Elm so that we could piggyback on my development for the elm ecosystem. I agree that we should aim for a Roc solution.
Anton (Apr 24 2023 at 12:41):I agree that we should aim for a Roc solution.
I'm a little confused :sweat_smile:
Luke Boswell (Apr 24 2023 at 13:46):I'm a little fried rn, I'll be able to give more detailed thoughts in the morning. I'm certainly keen to help out with this, and I think elm-book is awesome.
Georges Boris (Apr 24 2023 at 14:30):@Anton haha I mean, I'm making it for Elm packages - however, I'm trying to built the webserver using Roc.
for Roc, at first I'd try to use the same setup but also adding compatibility to Roc packages so I could also list packages available, their docs, and if you wanted you could even use Elm to create interactive widgets for your Roc package/guides.
later, I could expand that, given we have some standard UI platform, so that you could also write these widgets in Roc. I could also create Roc specific features, etc.
Anton (Apr 24 2023 at 14:51):Right, I think I understand. In an earlier discussion about a docs API, Richard did mention a key advantage of static files:
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
I also remember Richard talking about minimizing centralized hosting for packages as well. This proposal would take us in another direction in that regard
Georges Boris (Apr 24 2023 at 15:30):well, not necessarily - I would only need to access a centralized repository of available public packages. this would need to exist in someway, right? (repository pointing to existing packages, not necessarily hosting them)
Georges Boris (Apr 24 2023 at 15:31):the approach I'm taking makes it also possible to point to an ad-hoc repository and automatically generate docs for it. which might be useful for development or private packages.
Anton (Apr 24 2023 at 15:35):this would need to exist in someway, right?"
yes, correct
Georges Boris (Apr 24 2023 at 15:36):as for static website - I'm focusing on this with lazy static generation. versions are stored after first request, but I'm not focusing on no-javascript since I'm developing features like search, you can use interactive components, etc.
Anton (Apr 24 2023 at 17:08):That does sound good :)
Other people here have more experience in this area so I encourage them to weigh in as well.
Richard Feldman (Apr 24 2023 at 17:29):as for static website - I'm focusing on this with lazy static generation. versions are stored after first request, but I'm not focusing on no-javascript since I'm developing features like search, you can use interactive components, etc.
so I've spent some time talking to Ashley Williams, who has worked on both Cargo and npm, about how to design package websites with scaling in mind, and one of my main takeaways is "minimize hosting costs at all costs"
Richard Feldman (Apr 24 2023 at 17:31):lazily rendering static content could work for that goal, but I'm not sure what the advantage would be in practice compared to rendering it ahead-of-time
Richard Feldman (Apr 24 2023 at 17:33):rendering ahead-of-time means minimal latency between first request and first response (since the rendering has already been done, it doesn't need to do it on the fly before the respones can happen) and also that there can't be a scenario where the rendering server (assuming it is a single server; if it's a serverless function or something this isn't a concern) gets overwhelmed by too many requests for lazy rendering coming in at once, possibly resulting in timeouts for people trying to view docs that they were told would be available
Richard Feldman (Apr 24 2023 at 17:34):lazily rendering seems to only have an advantage in the exact scenario that nobody ever views the docs even once, not even the person who wrote them verifying that they're up...which seems like it would happen basically never? :sweat_smile:
Richard Feldman (Apr 24 2023 at 17:36):I don't think no-javascript is a hard requirement, but I do think docs pages need to be useful without javascript, e.g. they still work as documentation even if someone has JS disabled
Richard Feldman (Apr 24 2023 at 17:37):so maybe some features like interactive code example or search don't work, but they degrade gracefully - for example, if you view the current docs with javascript disabled, the search box doesn't even appear (since it wouldn't work), and the entire navigation tree is expanded. I'd like to keep that mindset for any future enhancements that require JS
Richard Feldman (Apr 24 2023 at 17:42):I think whatever we do for making interactive things in documentation, we should make it so that the language people use to implement those is Roc, not Elm or JS. One of the reasons Roc doesn't have the equivalent of a package.json or elm.json or whatever.yaml for specifying package dependencies (instead they're just in your main.roc file as part of Roc's syntax) is that I want to minimize the number of other languages and technologies you have to know in order to use Roc. That absolutely includes JavaScript, HTML, and CSS, and by extension Elm as well. Right now it's Roc and Markdown and that's it.
Richard Feldman (Apr 24 2023 at 17:44):part of the reason for this is so that the editor can remain scoped to just Roc code (e.g. if we use Elm or JavaScript for docs, then now either the editor needs to have nice support for Elm or JavaScript, or else we have to say "if you want to write docs for your Roc code, you need to use a different editor for that," neither of which I see as desirable), and also to remove barriers to people being able to write the best documentation
Richard Feldman (Apr 24 2023 at 17:47):obviously it would require more work to make it possible to do interactive examples in docs that can run in the browser (without people needing to learn CSS; I'd consider that basically a hard requirement, not just because of learning curve for Roc programmers who don't already happen to be comfortable doing frontend web development, but also because allowing arbitrary CSS is a security concern), but given that we already need a UI system that could work in the editor (e.g. for editor plugins), it may not be so much more work to get that system that we need already to work in the browser too via wasm
Richard Feldman (Apr 24 2023 at 17:49):so a design for interactive docs I think would be really cool would be one where the way you specify them is not browser-specific at all; rather, you write Roc code which describes the examples, it gets compiled to static content that can be viewed in the browser, and then in the future we can also take that exact same Roc code and render it in the editor just using native graphics APIs
Richard Feldman (Apr 24 2023 at 17:50):and since it's not coupled to the browser in any way, including layout specifications being decoupled from CSS (like how elm-ui decouples layout from CSS), the editor doesn't need to include an entire browser engine just to render these interactive docs examples; they can Just Work in both the editor and in a browser
Georges Boris (Apr 24 2023 at 17:57):lazily-rendering versus ahead of time is useful for when you're building something that changed in just a few small places. a package website is 100% that scenario since usually you will only get a very small subset of packages updated across releases.
Georges Boris (Apr 24 2023 at 18:00):I understand the design goal you mentioned, richard - however, wouldn't it also be useful to expose package information through a common contract so that external tools can be developed?
Elm is closed in so many ways, however, having a json output of the docs for all packages enabled the community to build a lot of cool tools. Would be a shame if Roc made this impossible by only expising docs through coupling it to the compiler/editor.
Richard Feldman (Apr 24 2023 at 18:35):I understand the design goal you mentioned, richard - however, wouldn't it also be useful to expose package information through a common contract so that external tools can be developed?
what do you see as both the pros and cons of this approach?
e.g. what gets better and what gets worse if we expose that?
Georges Boris (Apr 24 2023 at 22:47):imo, we gain the benefits of allowing community projects to be built on top meta information about available packages and their internal docs/types/functions, etc.
the con would be the maintenance burden of exposing that API but if a goal of doing similar stuff exists - this internal representation will need to be already available in some form, which would decrease the burden by quite a bit.
for this particular project - which I will built regardless for Elm - it would be great if I could be useful for the Roc community and provide something useful in the short term and possibly refactor it as the language matures so that it can be maintained using only Roc, rendering the plugins, etc. in the meantime, there could benefits of having a package listing website with a dedicated maintainer, features like search, community engagement, rich guides, etc. do you think it would detract from something core to the core development?
Luke Boswell (Apr 25 2023 at 01:37):From what I read here I think it sounds like a great idea. There are definitely open questions which we can explore, and some pretty clear requirements. If it's not too much additional work to get a proof of concept up for a Roc package, I think it is worth exploring. We may choose not to go that specific direction ultimately, but I think there is likely a lot of good ideas which may contribute to improve the Roc docs experience. I'm keen to assist here George, may be we can jump on a call and we can explore the idea? It was definitely something I spent a fair bit of time thinking about previously, and with our progress on static-site we are may be pretty close already.
Richard Feldman (Apr 25 2023 at 04:18):interesting - the main con I was thinking of is ecosystem fragmentation
Richard Feldman (Apr 25 2023 at 04:18):like one of the things I really appreciate about package managers is that there's one place I can go to to get all my docs
Richard Feldman (Apr 25 2023 at 04:18):and they're all in the same format, which means I have a lot of effective muscle memory for how to navigate them quickly to answer my own questions
Richard Feldman (Apr 25 2023 at 04:19):whereas I remember in the old JavaScript days it was pretty much every package does its own thing for docs, and the result is that it always takes me longer to navigate around and get authoritative answers to my questions
Richard Feldman (Apr 25 2023 at 04:21):whereas having one place everyone goes for docs, and where everything is presented in a consistent way, reminds me of the tradeoffs of code formatters: there's a benefit to the consistency, and the cost of that consistency is that there's less opportunity to experiment with different ways of doing things
Richard Feldman (Apr 25 2023 at 04:22):like with code style, docs are an area where I appreciate both consistency and centralization - and opening up an API and encouraging everyone to build third-party tools for browsing and interacting with docs seems like it would go against both of those, and I'm not sure that the benefits of what people would come up with would outweigh the drawbacks of less consistency and more fragmentation
Richard Feldman (Apr 25 2023 at 04:25):that said, I do think storybook is a compelling example, and I'm open to the possibility that maybe having something like that be separate from the built-in roc docs (but perhaps facilitated by them) could make sense
Richard Feldman (Apr 25 2023 at 04:26):come to think of it, roc glue is already pretty close to this :thinking:
Richard Feldman (Apr 25 2023 at 04:26):it's coupled to platforms at the moment, but I already want to expand it to work on arbitrary interface modules too
Richard Feldman (Apr 25 2023 at 04:27):and although it doesn't at the moment, I do think it would be good if glue exposed documentation strings so you can pass those along in your glue generation
Richard Feldman (Apr 25 2023 at 04:28):but if we had both of those, I suppose anyone could just run roc glue and have the output be .html/.css/.js files that comprise interactive docs
Georges Boris (Apr 25 2023 at 04:49):I agree that fragmentation can be a bad thing... though I'm not sure about the ideal way to prevent that.
Seems like owning too much might be risky. Like, I'm not saying my project would be the ideal docs experience for all Roc projects, but then again, it may be if people like it.
Having a deep compiler integration might give the "core" documentation an edge over anything else, but maybe that won't make the experience be the preferred one for most people, maybe it will.
Btw, the same argument could be made for the editor. I'm saying that even though I was mainly onboard with not working on a LSP or treesitter for giving the editor time to blossom.
That being said, maybe some projects are worth an initial free exploration before the community decides on one particular approach that can become the "official" community supported approach.
It would be great if other passion projects with unique visions could emerge around Roc even if they are not curated by the same language designer.
With the proper care about what to expose or not, this could be seen as another way to separate a safe core and other emerging "platforms", if you will.
Georges Boris (Apr 25 2023 at 05:37):I ended up thinking more about that - in the elm ecosystem we have elm-review, which is jeroen's passion project that would probably not be possible if it required core language designers approval even in the exploration phase (this becomes more true as the community grows).
elm-review ended up being possible without pluging into any info from the compiler itself, but I wonder what else could have been possible if it did.
I also imagine things like runtime loggers and debuggers emerging if more api's were open for this kind of extensions. I can imagine it wouldn't harm any of the language core values (imo the compiler and package/version manager) but maybe we would have much better tools than the elm debugger.
I've kinda drifted from the main topic but I think these points are related.
Richard Feldman (Apr 25 2023 at 12:51):It would be great if other passion projects with unique visions could emerge around Roc even if they are not curated by the same language designer.
I think this can be awesome, but this is also the root cause of "framework churn fatigue" that people complain about in the JS ecosystem - and one of the common things people say they like about Elm is that Elm doesn't have this churn
Richard Feldman (Apr 25 2023 at 12:52):but elm-review is a good example; there was no first-class support for that, but Jeroen did it anyway :big_smile:
Richard Feldman (Apr 25 2023 at 12:52):arguably the bar was set in the right place there!
Georges Boris (Apr 25 2023 at 14:43):yup - so I guess I'll continue with my elm-focused project. I'm aiming at releasing it at elm-camp (late june) - after that maybe I can do a demo for people here so we can brainstorm and see if there is interest in me porting it to Roc (porting but with intents of making it its own thing)
Richard Feldman (Apr 25 2023 at 16:16):love it! :100:
Notification Bot (Apr 28 2023 at 10:53):13 messages were moved from this topic to #ideas > multi-purpose glue by Anton.
Last updated: Jun 16 2026 at 16:19 UTC