Programming.md

I arrived here after hearing that Suave may use Hopac. https://twitter.com/henrikfeldt/status/955101969487683584

This is potentially a really great thing. However it does mean that Hopac is going to need to bolster its documentation. Really it seems like the documentation is already there but for some reason it’s squirreled away in a repository folder.

The programming.md starts with a relatively understandable guide which should probably be placed front and center. If you start with how a person can use a thing, and how it might be beneficial to them they’re much more likely to take it up than if you show them a long api list, or some other library that inspired you. I had to actually look through the repository to find this document and frankly it was the most helpful document by a mile.

However it abruptly switches to operators defined by Hopac with no explanation about how to use them. We should be mindful that this is an F# library not a Haskell library, and I think that the Programming.md is a wonderful getting started guide, but it should probably include the information from the Operators.md and a brief description of how they are used. I honestly had to stop at this point because while I had seen the bind operator before, I had never seen a >==. which I have no word for.

I still think even in it’s present state it’s the best introductory documentation in the repository and should maybe be listed as part of the Getting Started Guide.

[voronoipotato]

Suave actually has excellent documentation for someone wanting to get started. It avoids getting in the weeds and focuses on what’s important for using the library. I suggest we use their programming guide as a model for “Getting started”.

I’m actually a good candidate for proofreading this because I know absolutely nothing about Concurrent ML, I’ve never even used ML. I know very little about the operators you’ve defined. I’ve used suave naively and it seemed to work fine for me. So if you can make documentation that I can understand then anyone who has successfully used Suave should be able to use Hopac because I’m a pretty low bar.

[haf]

Understandable. I feel passionately about having software that is approachable. However, me moving to Hopac is something I’ve done the last 3-4 years and that’s after reading lots and lots about multiprocessor programming, interleaved concurrency and having written C# with its Task-based API for soon 14 years (before that IAsyncResult, Monitor, locks etc). Writing in concurrent programs in Hopac is part of the most fun I’ve ever had as a programmer, and I would like people to experience that joy.

The only real difference to a Suave user would be that it would say Job<Thing> or HttpContext -> Job<HttpContext option> or the like instead of Async. The code you write would be almost identical.