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/