Package documentation not as approachable as it maybe could be about operational HOT 5 CLOSED

Thanks a lot for your detailed report, Gábor!

The main lesson that I take away is that the package documentation / description should provide more context instead of just referring to someplace else. My assumption was always that people would read "The Operational Monad Tutorial" first to get some intuition and then go to the package, but that is apparently not the case. There's probably no way around reading the tutorial, but that doesn't mean that the package description should not provide some context.

But if I'm someone who doesn't already know what this is, and isn't definitely sure that it's something I want to use, then the amount of effort I'm going to be willing to expend to figure it out isn't going to be limitless.

That's a very good point! When writing a tutorial, I always imagine that the reader has a severe attention deficit, so I have to state the point simply and using few words. Of course, readers are not stupid; it's just they don't necessarily have much attention/effort to spare at that moment. The same rule applies to package documentation, but organization is much trickier for me as there are many more entry points.

from operational.

I have uploaded a new version to hackage that hopefully improves the documentation. Would you be willing to take a quick look, Gábor?

from operational.

Much nicer, thank you!

A few areas of potential improvement:

• In the runCustomMonad section in the overview, I think it would be helpful to have some actual code in the 'Return a' and 'AskUserInput :>>= k' cases, rather than just '...', to demonstrate what sort of thing you would do with the 'a' and 'k' values you got. Obviously the functions used there wouldn't be implemented anywhere, only to illustrate. Then in the explanation underneath it would mention the other things you could have done instead (as now), that you can write different run/interpret functions that do different things, etc.
• If it's not too huge, it would be nice to have the definition of the Stack type included in the stack machine example.
• The constructors for ProgramViewT could use some documentation, i.e. what they represent and what the various parts of them are.
• If I'm not mistaken the list monad transformer example should be under viewT, not liftProgram.

I think that's all. Thanks!

from operational.

I have implemented your suggestions and uploaded a new version.Thanks! Let me know if there is anything else that I should improve.

from operational.

Also not that the result of the run function does not need to be a monad at all.

The first not should be note, and it might be more correct to say "in a monad". That's all for now :)

from operational.