Re: [boost] [outcome] Requesting second pre-review of Boost.Outcome tutorial

Subject: Re: [boost] [outcome] Requesting second pre-review of Boost.Outcome tutorial
From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2017-01-16 11:05:15

On 16/01/2017 10:47, Gonzalo BG wrote:
> Hi Niall,
> 
> I wanted to invest 5-10 minutes into learning the library and this is my
> feedback about the tutorial. The tutorial is too long, and it goes too deep
> into unnecessary details, and it does not teach me properly how to do the
> basic things with the library (in the default configuration). The reasons
> are the following:

That's really great and detailed feedback. I also got some good feedback
from SG14. I'll take a third attempt at rewriting the documentation.
It's lucky I'm currently out of contract, phew ...

Regarding specific points of yours:

>   - Examples that show how to use the whole API of result/outcome,
> composition (error values, functions chaining errors, ...), ... for dealing
> with optional values and doing error handling! (which is the raison-d'etre
> of the library)

I had one of these in the first write of the tutorial where I had taken
a real world actual use case of Outcome and reduced it to a minimum
standalone snippet. Feedback from here said it was too complicated, too
long and needed to be removed, so I deleted it.

I think what you're asking for is cookbook of common use case sequences?
I'll see what I can do on that.

>   - Remove any mention of optional since it raises too many questions
> (another optional type in Boost? why can't Boost.Optional be improved? ...)

Given feedback from elsewhere, I think sadly I'm going to have to drop
the monadic programming support too. Too many people want a Hana style
monad, and I have no personal need for one of those especially when said
people should just go use Hana. I'll leave the implementation in the
code which can be enabled with a macro, but drop any mention of monads
completely from the docs.

It's a shame though. The monadic programming API is way better than
Expected's. Much nicer to write against. But it's hard on the compiler,
and its limitations will disappoint many keen on monadic programming. As
with Expected, it probably needs to disappear entirely to pass a peer
review here.

> I hope the feedback helps, and sorry if it sounds harsh. As an error
> handling solution, how to use the library to do error handling can probably
> be explained in full with examples in 1-2 pages, mainly because the API is
> both simple and nice. The current tutorial does not reflect this but with
> more time you can probably make it do so.

Thank you so much for the feedback. I'll try a third rewrite. Please God
let the third time be lucky, writing documentation seems to never end ...

Niall

-- 
ned Productions Limited Consulting
http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/