Component-based examples for Core functions

[purefunctor]

I think a good way to document the functions in Deku.Core is to have a component library for it à la ocelot

[mikesol]

I'm not sure what to do about Deku documentation these days.

There's a small group of folks for whom Deku fulfills a specific need (most often speed) that tend to get up to speed by chatting on the Discord. The existing documentation is an ok-ish reference, as are the few articles and sample applications on the web.

My concern is that we don't have enough of a signal that Deku's interesting to a wider audience. It could be that the framework will only be used by its current user-base, all of whom understand the ins and outs of the framework quite well. Of course, if someone wants to document Deku while learning it à la Jordan's Reference, that'd be great!

[JordanMartinez]

I think Deku is interesting because it is faster than Halogen and has serve-side rendering. However, I haven't looked much more into it because of the documentation situation. There's also the additional learning curve of it using FRP. So, I'm not sure how much of my Halogen/React component/hook-based knowledge transfers to this framework. So, even before learning how to use this framework, part of me feels like I would need to better understand the core concepts of FRP before I should start looking at this framework.

Also, it's not just this library that needs to be documented. What about bolson and hyrule, which are both dependencies of this project? By their name alone, it wasn't immediately obvious to me as to what each one does. I'd guess documenting those libraries would also be needed at some point as well?

And lastly, I've seen a lot of changes being done on this library and its dependencies. So, I'm also hesitant to try it out because it feels like this library isn't "stable" yet.

[MonoidMusician]

Bolson is a “library's library” (something we don't see a lot of in the PS scene) – it's a library that's meant for implementing libraries like Deku, but as a user of Deku you really don't see it much. You can explain Deku on its own without explaining Bolson.

Things are still changing frequently as we figure out details, but it is mostly details. Sometimes it's pesky implementation details leaking through. (Turns out DOM isn't compositional 😅.) But the core ideas remain the same, and so code changes tend to be on the trivial side (renamings, etc.).

But yeah it takes some knowledge of FRP to hop into Deku. Because you're architecting a whole application based on FRP (and nested and recursive events in particular), you can quickly run into places where you need to know how it works pretty thoroughly to not introduce subtle bugs.

[mikesol]

hyrule (my fork of Phil's event) would be a good place for us to put effort into documentation. hyrule has wider usefulness than Deku, and by documenting it better, we'd help folks feel more comfortable with FRP. @xvaldetaro has done some nice work with hyrule-paraglider, and we can likely build upon that to create a 0-to-hero FRP guide.

As for Deku's documentation, perhaps the best resource atm is https://github.com/mikesol/purescript-deku-realworld/ and its wiki at https://github.com/mikesol/purescript-deku-realworld/blob/main/wiki/templating.md. I genuinely want to help people that are interested in learning Deku, but documentation and teaching materials are not my strong suits (I enjoy writing articles, though, and I very much enjoy helping folks on Discord).

The framework is getting more and more stable all the time, but it's still a faster target than other frameworks. The current package set on trypurescript, which is quite recent, is still a couple major changes behind both hyrule and deku due to this velocity. For example, the function fromEvent no longer exists, even though it's used in the trypurescript examples. Folks using Deku tend just to point to main and pester me if/when I break stuff. But the framework really does get faster & more compositional all the time, so the pace of change feels like a justified-though-imperfect means to an end.

If you ever want to dive in to make a hello-world app, hit me up on Discord! I can help you with the setup. I'm using vite these days for https://joyride.fm & it's pretty painless.

[JordanMartinez]

the framework really does get faster & more compositional all the time, so the pace of change feels like a justified-though-imperfect means to an end.

That's kind of my point. It's not really worth documenting this project until it further stabilizes. Otherwise, you're wasting time on writing docs that will be out-of-date not too far into the future.

[mikesol]

Closing this as there are now pretty comprehensive docs on https://purescript-deku.netlify.app. Issues with documentation can be posted on its GH repo, https://github.com/mikesol/deku-documentation.