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