Explore making new site

[delaneyj]

Better, clearer, more concise, and more informative site.

[bencroker]

Fitter, happier, more productive
Comfortable, not drinking too much
Regular exercise at the gym three days a week
Getting on better with your associate employee contemporaries
At ease
Eating well
No more microwave dinners and saturated fats
A patient, better driver
A safer car
Baby smiling in back seat
Sleeping well, no bad dreams
No paranoia
Careful to all animals
Never washing spiders down the plughole
Keep in contact with old friends
Enjoy a drink now and then
Will frequently check credit at moral bank
Hole in wall
Favors for favors
Fond, but not in love
Charity standing orders
On Sundays ring road supermarket
No killing moths or putting boiling water on the ants
Car wash, also on Sundays
No longer afraid of the dark or midday shadows
Nothing so ridiculously teenage and desperate
Nothing so childish
At a better pace
Slower and more calculated
No chance of escape
Now self-employed
Concerned, but powerless
An empowered and informed member of society
Pragmatism, not idealism
Will not cry in public
Less chance of illness
Tires that grip in the wet
Shot of baby strapped in back seat
A good memory
Still cries at a good film
Still kisses with saliva
No longer empty and frantic
Like a cat
Tied to a stick
That's driven into
Frozen winter shit
The ability to laugh at weakness
Calm
Fitter, healthier and more productive
A pig
In a cage
On antibiotics

[Regaez]

This issue is a little light on details about what constitutes a better, clearer, more informative site, so I thought I'd leave a thought I'd had recently for input/discussion.

One thing I have noticed since lurking on the Discord for a while is that there is a big emphasis on the approach of merging fragments first and only turning to signals when absolutely necessary, but it seems to be contradicted by the structure of the documentation.

When you visit the Datastar website, the "getting started" guide starts pushing signals immediately. This makes it feel like signals is the way you should be doing things, when it would rather appear that the SSE actions are being recommended as the approach to follow first and foremost.

Since signals promote using/storing state on the client, I believe this is detrimental to new users (particularly those coming from a SPA-centric world) learning and understanding what Datastar is as a library/framework, its paradigms, and how one should best proceed with using it and building sites/apps at the beginning.

Are there any plans to overhaul this section and provide more guidance with regards to "best practices" for using Datastar?

[bencroker]

Thanks, @Regaez, this is valuable feedback. You’re right that the Getting Started guide starts off talking about signals and frontend reactivity. This is intentional, as it is the gentlest way of introducing the reactivity engine (the library) and the unique Datastar syntax to people seeing it for the first time. SSE event and backend actions come later because they are more involved. But your point is very much noted, and we do have a page planned to help guide people on hypermedia-first approaches.

[Regaez]

You’re right that the Getting Started guide starts off talking about signals and frontend reactivity. This is intentional, as it is the gentlest way of introducing the reactivity engine (the library) and the unique Datastar syntax to people seeing it for the first time. SSE event and backend actions come later because they are more involved.

I just finished listening to the podcast episode with JLarkey and after some consideration of points that he mentioned (as well as my own observations from following this project for a while), I would dispute this "intentional" approach and suggest that perhaps it should be changed.

JLarkey talked a lot about the messaging of Datastar; I think there was some miscommunication during the podcast which resulted in some of his concerns being dismissed by @delaneyj, but ultimately I believe he had some valid concerns that could be addressed.

I would try to expand on some of these points, adding my own perspective, as I believe that these are pertinent to the advertising/promotion of Datastar via the website/documentation.

1. Framework vs Library

There's a lot of talk (on Discord, in podcast, etc) about how "Datastar core" is the library, which is just an engine to consume data-* attributes and a few attributes to declaratively define reactive signals, and then there's the "Datastar framework", which is a collection on plugins building on top of this, meant to provide everything for a full-fledged hypermedia driven application.

I think Datastar the library is an implementation detail and is emphasised too much, particularly for newcomers to Datastar. I believe that the true value of Datastar lies in the framework, not the library, and that the framework should be pushed first and foremost.

For example, the Datastar website currently advertises prominently on the homepage: "The hypermedia framework." However, when you go to the "getting started" page, it starts talking to you about using signals and the reactivity engine. From everything I've seen thus far, the framework would have you keep things simple by sending large HTML fragments down and letting idiomorph merge it into the DOM for you. Signals are only to be used rarely, if at all, and are only really intended for ephemeral client-side state.

As mentioned in my other comment above, I think the prominence of signals being introduced early into the onboarding journey gives too much weight and emphasis on a tool that should be sparingly used (insert "hammer, everything a nail" quote).

I believe Datastar currently has somewhat of an identity crisis in its messaging; it's trying to advertise that it is both a library and framework, and not doing a very good job at either. I think the "library" messaging should be abandoned, or relegated to a small section in the documentation (for example, perhaps targeted to those looking to extend the framework with their own custom functionality).

2. Core concepts

On the homepage, it explicitly says "by embracing simplicity, and building on first principles, everything becomes cleaner and leaner." However, I don't really feel like these "first principles" are captured anywhere yet outside of Discord; although the "Stop overcomplicating it" guide kind of attempts to, and perhaps also the SSE essay starts to touch on it.

I see a lot of discussion in Discord where people are struggling to "get" how best to use Datastar; I think that leaning into being a more opinionated framework, with more explicit conceptual documentation, could be helpful for newcomers to understand how to best leverage what Datastar can do (and not have to explain it over and over again on Discord).

Now, I don't mean changing the API to be more opinionated, but rather capture and convert the valuable knowledge floating around in the head of @delaneyj and from various Discord chat members and publish some documentation that:

• Clearly outlines the core principles of the framework (i.e. backend contains state, fat updates first, fine-grained signals last, etc)
• Recommends best practices for building sites/apps,
• What constitutes "idiomatic Datastar"
• When not to use Datastar

Datastar, like (dare I say?) React, is powerful in that you can do a whole lot of stuff in a whole lot of different ways; it is a toolbox containing many tools.

However, one of the downfalls of React was that, beyond its fundamental paradigm, it was quite un-opinionated with how to do things (it also positions itself as a "library") and has gone through several evolutions over the years. Inevitably frameworks like NextJS rose in popularity because they prescribed a certain way of doing things, which was easier for users to onboard, understand, and be familiar with/have transferrable knowledge across application codebases (particularly relevant in larger organisations).

The Datastar framework is promoting a way of building applications that (one could argue) goes against the modern/de-facto way of building for the web. Thus, I think there should be more guidance provided with the way of the Datastar framework, i.e. when it is appropriate to use each feature/plugin of Datastar, so developers don't end up shooting themselves in the foot with a nailgun, when they should have been using a screwdriver instead. Datastar, the hypermedia framework, should be more dogmatic.

I know you are planning to write "How to guides" following the Diataxis method, and so it remains to be seen whether these would sufficiently cover this topic. I have a suspicion they won't be, as I think this topic tends more towards the "explanation" part of Diataxis. There's been much talk of "the great unlearning" with regards to Datastar; I believe this "unlearning" is hampered by the fact that the core concepts/principles of the framework are not better explained.

3. Accessibility

I would love for there to be more emphasis in the documentation/guides/examples of how one should go about using Datastar and creating accessible experiences. For example, ensuring that there are no code examples containing div elements with on-click handlers (just because you can, doesn't mean you should).

Or, demonstrating best practice patterns to follow with Datastar regarding things like updating aria attributes, particularly when it comes to the client-side reactivity aspects of the framework. For example, the data-indicator attribute comes to mind as a good candidate here.

Furthermore, there is no documentation that I've seen that covers what accessibility features are handled for you automatically by Datastar. Perhaps there are none? Does it apply aria-live/aria-busy for you to DOM elements that change on morph? Should you do this yourself? Are developers even aware that they should do things like this?

One could argue that such a topic is outside the scope of responsibilities of the framework, but as Datastar brings declarative reactivity to the browser where there was none before, if the framework does not encourage/promote accessible experiences, it will be to the detriment of many users that rely on web accessibility.

4. HTMX

I know about Datastar's origins as a "plugin-based HTMX", but I think the marketing around Datastar (particularly the examples page) showing how Datastar can:

• "do the same stuff" as HTMX, or
• "do it better" than HTMX, or
• "do it with less code", or
• "do HTMX all as plugins"

is detrimental to Datastar forging an identity of its own. I think there is too much direct comparison with HTMX and not enough emphasis on why Datastar is good in its own right.

For newcomers who are not at all familiar with HTMX, all the comparisons to HTMX are meaningless. The population of HTMX users is tiny in comparison to other web technologies/frameworks; many developers discovering Datastar will be coming from React/SPA-land and from a certain way of building web experiences that is fundamentally so different. There's not a lot that really caters to this (larger) demographic at the moment.

For those coming from traditional MPA sites/apps of >10 years ago (but also haven't used HTMX), the "Datastar way" may feel more familiar, but again, with the emphasis and comparisons against HTMX, it distracts from the message of how Datastar can enhance the traditional MPA approach.

Generally, I think Datastar needs to step out from under HTMX's shadow.

5. "Smallest"

This is an issue JLarkey raised, that Datastar claims to be the "smallest" framework, but this claim is baseless as it is comparing apples to oranges. React, Svelte, Solid, Vue, HTMX, Alpine, etc all contain different sets of functionality. That Datastar lays claim to being the "smallest" of them all is drawing an arbitrary line in the sand around some subset of features.

I would rather suggest that the messaging here would be better served to emphasise the performance benefits of Datastar being small (not the smallest). @delaneyj raised some good points in the podcast episode around cachability of Datastar, page weight, download times, etc. For too long the web industry has over-relied on JS-heavy frameworks and the users have paid the price for it (refer readers to The Performance Inequality Gap).

Lean into the reasons of why Datastar being small is good because (despite claiming otherwise on the homepage) saying "the smallest" really does come across as just a "vanity metric" and meaningless bragging. Sure, sell Datastar as the paradigm-altering way of the future that the web could be, but I think there should be more validation of those claims with substantive reasoning.

6. Build "anything"

One thing that was also touched on in the podcast by @delaneyj and I would love to see captured on the website is when not to use Datastar. Just because you can, doesn't mean you should.

Yes, you could build anything with Datastar; but should you, really? No, sometimes you simply don't need it. Sometimes you really only need a small fraction of it.

I think there was a lot of value in what @delaneyj was trying to convey in that segment that may have gotten lost in the discussion as debates over what constituted SPA vs MPA, and SSR vs hydration were bouncing around at the same time. There could be a lot of value in actually trying to capture and condense those thoughts into a more well-formed essay, or as a page in the documentation positioned shortly after "getting started" (i.e. here's how easy it is to get started... but do you really need it?).

7. Spec compliance vs standardisation

This is not so much a topic for the current website itself (as I don't recall seeing it explicitly mentioned anywhere) but more to do with the general marketing of Datastar. I mention it here simply due to the other podcast references and perhaps there's something here that could be taken into consideration when improving the website.

In the podcast episode, JLarkey took issue with Datastar positioning itself as both a "spec-compliant" framework and as a framework that would eventually "disappear" if it were to become standardised in the web spec. I don't believe these are at odds with each other as JLarkey said; I believe the ideas coalescing behind the Datastar API hold a lot of potential for the future of the web, but the path to get there is what's important.

I believe JLarkey was concerned over the means of standardisation since, by using data attributes, Datastar remains spec-compliant today and will not clash with any future additions of DOM element attributes, but also because Datastar uses data attributes, its plugins (and their API) will never inherently become part of the spec because the spec has declared it will never add or associate any behaviour with attributes that are prefixed with data-, i.e. data-signals-* can never become standard. This means at some point developers would likely need to do some form of migration to adopt any "new" standard declarative markup.

However, Datastar's spec-compliance is important because its API remains both backwards and forwards-compatible with any developments in the web spec. Any conflict in behaviour of those data-* attributes is entirely the responsibility of the developer to resolve (i.e. clashes with third party libraries), but the spec-compliance of the Datastar API is an crucial factor on the reliability and longevity of the framework (i.e. such as the idea of the 100 year application). You also won't need to migrate to a new, breaking version of the framework to be able to keep using it, even if some features become standardised (it just may result in better performance and smaller framework overhead).

Generally, I think the reasoning behind why spec-compliance is important and a valuable asset to the Datastar framework is missing (i.e. a lot of "HTMX isn't spec compliant and that's bad" was being said without expounding on why) and what I think could be improved about the messaging regarding web standardisation is that it is not the implementation of the API (i.e. the plugin attributes) that Datastar wants to see standardised, but rather the concepts that are behind it and powering the framework, i.e. a means to accomplish declarative, reactive hypermedia. Mechanisms within the browser to have HTML react to signals, execute expressions, dynamically and asynchronously manipulate the DOM via declarative markup.

[delaneyj]

All of these are great points. The way to actually make the impact you're talking about is to submit documentation PRs

[bencroker]

Once again, @Regaez, this is all valuable feedback and I think it would make a great article/essay. We need people besides @delaneyj and I writing about Datastar, and you apparently have a lot of thoughts and are a great writer. Please keep in mind that Datastar is FOSS and if you want something to change, you must be willing to contribute in a tangible way.

Also, FYI, this issue is about a site redesign/restructuring, not a rewrite of the documentation. If you want to contribute in a more meaningful way, please consider contributing with a how-to guide, see #516.