Getting started documentation

[noughtmare]

I wanted to quickly write an example of a handler in an effect system and I have been recommending effectful, so I thought why not use that in the example.

So, I opened up Hackage and went to the effectful package. The first problem I noticed is that it has no documentation for the Effectful module. That's unfortunate, but the description does say that you can go to the effectful-core package to view that documentation.

There I find a nice introduction which almost has what I need:

The library provides:

• The Eff monad that tracks effects at the type level. This is going to be the main monad of your application.
• A set of predefined, basic effects such as Error, Reader, State and Writer.
• Utilities for defining new effects and interpreting them, possibly in terms of already existing ones.

That last bullet point is exactly what I need, but alas, it does not link to further explanation.

That hackage documentation seems like a dead end.

At this point I backtracked and went to the readme here on GitHub, but the only relevant part seems to be the links to examples:

For the examples see the Introduction sections of Effectful.Dispatch.Dynamic and Effectful.Dispatch.Static.

I guess I could look at that, but I'd have to make a choice between Dynamic or Static effects which puts me off.

So, I'd suggest:

• Add links in that first "The library provides:" section of the main documentation.
• Choose either Dynamic or Static to be the default and first introduction and write a focused "getting started" documentation for that.

But I'm open for other ideas.

[arybczak]

That last bullet point is exactly what I need, but alas, it does not link to further explanation.

Isn't what you want above the bullet list? :thinking:

[arybczak]

Choose either Dynamic or Static to be the default and first introduction and write a focused "getting started" documentation for that.

Yeah, I can add a note that when in doubt, start with dynamic dispatch. Especially since there will be some upcoming changes to Effectful.Labeled that make it very easy/efficient to work with dynamic labeled effects.

[arybczak]

I've put a PR that should fix this. @noughtmare can you have a look?