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

Subject: Re: [boost] [outcome] Requesting second pre-review of Boost.Outcome tutorial
From: Gonzalo BG (gonzalobg88_at_[hidden])
Date: 2017-01-16 05:47:22

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:

  - Too much unnecessary discussion about implementation details. During
the first 5 minutes of learning the library, I do not care that optional,
result and outcome are implemented using basic_monad.
  - Too much unnecessary discussion about performance. During the first 5
minutes of learning the library it is enough to tell me that it provides
zero-cost abstractions and maybe link that to a performance section _with
data_. Telling me how many cycles something costs is unnecessary and
useless without showing me data (since at this point in my learning of the
library I am still very skeptic about its usefulness).
  - Fundamental concepts are not explained in an idiot-proof way. I have to
skim through a wall of text to figure out when do you use outcome vs
result. IIUC result is faster, so if you can use it you should. The docs
should put fundamental concepts upfront. You can link to a performance
section for the details, but these do not add anything value during the
tutorial.
  - Too much non-c++ speak. For example, basic_monad raise warning flags
("Is that a base implementation for all Monads? (that cannot be true, does
the author even know what Monad is?, etc.)"), you probably want to call
that basic_outcome instead.
  - I have to read too much before actually getting to what Outcome does.
  - Too many superlatives and words devoid of meaning ("much more
comprehensive monadic programming interface", "ultra low runtime
overheads", "really elegant expression of error handling in C++", the way
of doing error handling in C++17 and beyond (20) ...). Basically reading
the tutorial feels like you are trying to sell me a broken car. The
tutorial uses lots of words to tell me how great the library is, but almost
no examples/data to show that this is the case.

How to improve the tutorial:

- Reduce the time needed to come in contact with Outcome. Put the code
examples at the beginning side-by-side if possible, e.g., show only C++
using throw, C++ using std::error_code, and C++ using Boost.Outcome, and
then tell me _as briefly as possible_ the advantages of using Outcome
(noexcept, composition, performance... don't use a wall of text!).

- Focus the tutorial on examples that show how to use the library and which
problems does it solve good:
  - 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)
  - If the examples show how good the library solves the problem it is
supposed to solve you don't need to tell me in the text!
  - Move all the performance-related discussions/details to a section which
first show the data, and then discusses it and convinces me with facts.
Just tell me that the library is a zero-cost abstraction (or fast), and
link to this section.
  - Move all the implementation-related details to a different section
about the implementation (e.g. how to implement optional using basic_monad)
  - Remove any mention of optional since it raises too many questions
(another optional type in Boost? why can't Boost.Optional be improved? ...)

- Make sure that the fundamental concepts are stated in a water-tight
easy-to-understand way, for example:
  - When to use outcome vs result: result is faster so prefer result if you
can
  - What does Boost.Outcome does? "Boost.Outcome provides an unified way of
working with result values that may become optional due to error conditions
or exceptions." (try to use C++-speak, do not mention Monad, do not use
complicated words that an user might need to google, ... i.e. keep it
simple).
  - use space (and user time) efficiently, e.g., the part of the tutorial
where you have three "What happens if..." can probably be summarized into a
small table (less words, a bit more visual, might be a more efficient way
of conveying the information).

- Change the tone of the tutorial. That is, go through:
  - every single sentence and evaluate whether somebody with less than 5
min experience with the library needs to learn this right now, or at all
(maybe delete it, maybe move it to a more advanced tutorial like the
configuration stuff or the basic_monad stuff)
  - every single word and evaluate whether it adds any extra meaning to the
sentence (in particular kill all those superlatives, they should be clear
from the examples or the data, otherwise I feel like I am being scammed).
  - remove non-C++ speak terms (like Monad), basic_monad raises to many
questions that aren't answered so maybe rename that to basic_outcome.

- Rethink whether to expose a boost::outcome::optional type in the library
at all. This is going to raise tons of questions during review (we already
have Boost.Optional and std::optional).

- Go through all functions in the tutorial and make sure they are linked
properly (e.g. the get and get_error member functions are not).

- Rethink the cheat-sheet:
  - move it to its own section
  - make sure that it solves its purpose, that is, for somebody who already
knows how to use the library but cannot remember how a function, macro, ...
was called, can the cheat-sheet answer its question in say less than 10
seconds? (e.g. the cheat-sheet of the Eigen library does a great job at
this).

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.

Bests,
Gonzalo