Hard to tell what Effect-TS does from the website

[PurpleBooth]

What version of Effect is running?

N/A

What steps can reproduce the bug?

Visit the website as a person new to Effect-TS

What is the expected behavior?

To understand what Effect-TS is does, and why I should use it

What do you see instead?

This is what I get above the fold in my browser. Which didn't really tell me anything.

Additional information

So both me and another person were looking at your website and readme and our first impressions (both independantly experienced) were confusion as to what the library does. After a bit of clicking around I worked it out but, it would be really cool if examples weren't hidden behind clicking on tick boxes, or tabs, and instead of the list before the fold was more... idk useful, it's a bit vuage.

Visually it looks really nice, but the design doesn't put front and center what the library does, or a list of tasks I can achieve with it.

I know this is a bit of a vuage bug report, and probably isn't a "bug" in the traditional sense, but hopefully it's helpful feedback regardless.

[unusualevent]

Same. Also the readme of github.com/Effect-TS/effect really doesn't explain 1) what this is 2) why I need it.

[fubhy]

This is a bug. And we agree that there's a lot of room for improvement. Thanks for reporting. If you have any additional, specicfic suggestions let's hear them!

[steida]

@PurpleBooth

Effect provides well-established patterns known from other languages to help you write better TypeScript code. Better means you don't have to reinvent those patterns but still have to learn them to appreciate Effect goodness.

Explaining new things on one page is impossible. Imagine Effect was a math. How would you explain the math on the one page? The website home page is more like an ad than the full explanation.

There is always room for improvement, of course. If you tell us which sentences are confusing, that would help us a lot.

[steida]

@PurpleBooth When I explain the Effect to people, I tell them It is a way to organize software code. Why does it matter? It matters a lot because software code that does a thing can be written in a thousand different ways.

The Effect is like a blueprint that helps you organize code. No matter what the code does, it always has the same structure and naming convention. Of course, to achieve such an effect, the developer has to learn the Effect.

Do you think this explanation is better?

[unusualevent]

It does a poor job of advocating for it. An ad has a clear pitch and explanation of why someone would use something.

https://vuejs.org/ ~ "build web interfaces" (for when JS is hard) https://getbootstrap.com/ ~ "build responsive sites" (for when CSS is hard) https://go.dev/ ~ "simple concurrent code" (you use it when you want basic C programming) https://www.erlang.org/ ~ "practical functional programming" (you use it when you want a telephony system) https://www.britannica.com/summary/mathematics - "the science of structure, order, and relation" (you use it when you want to understand patterns and solve problems)

I think your explanations are hard because it's coming off as nebulous.

Plus, functional programming is /one part/ of programming, just like linear algebra is only a subset of mathematic techniques.

[PurpleBooth]

For me there were two things at play, the above the fold content's bullet points

The following claims could be about any library that's somewhat popular.

• Maximum Type-safety (incl. error handling)
• Makes your code more composable, reusable and testable
• Extensive library with a rich ecosystem of packages
• Clustering and Workflows (Alpha)

You need Effect-TS's USP here instead. I am pretty new to this library, but I might say something like

• Functional types you know and love (and the safety they bring)
• Simple scheduling and cancellation of asynchronous work
• Clear interface for those new to functional programming
• Extensive library with a rich ecosystem of packages

You also have a big video on half of that space, I didn't watch that (others might, so me I would drop that, but ymmv)

Then the second thing that was in play, was that after I read the above the fold content, I skimmed down to find examples, and I didn't realise that the checkboxes were more than visual styling at first, and I didn't click through to the other example bits of code, they weren't clearly tabs.

Once I dove into the docs a bit more, I got really interested, and is perfect for de-taffling a parsing interface I have, but those were my first impressions.

Don't get me wrong it looks great, it just doesn't tell me what it is.

[steida]

Maximum Type-safety (incl. error handling)

Type-safe errors are unicorns in the TypeScript ecosystem. A few helper libraries exist, but no TypeScript library has type-safe errors. Type-safe errors are crucial. Imagine adding an error to some functions; suddenly, the TypeScript compiler forces you to handle them. That's only possible with typed errors.

[steida]

Makes your code more composable, reusable and testable

When you start using typed errors, the next immediate issue is how to compose functions returning such typed errors and how to handle them. Effect provides you with code for that.

Testability means you don't code against implementation but against interfaces, and implementation is pluggable, so you can switch real DB with test DB.