On 22 Nov 2016 at 1:33, Andrzej Krzemienski wrote:
I am very curious about your library, and about the subject. I would like evaluate it. But I am having problems going through the documentation. I was only able to figure out that it deals with returning either T or an information about failure, and that you believe it is the fastest solution you can get. But other than that, I am confused.
:(
I am very found of Robert Ramey's advice given in this talk: https://youtu.be/ACeNgqBKL7E?t=4m48s And I would summarize it as follows, does the first page of the documentation allow me to see and understand in 5 min what this library is for and how I will be using it.
I think for single purpose libraries where the reader already knows what they want and why they are reading the documentation e.g. serialisation then Robert's advice is gold. I think it's much, much harder for libraries which provide fundamental primitives because the uninitiated don't understand what the point of the primitive is yet. Remember the old unique_ptr vs shared_ptr vs auto_ptr discussions back in the day? People really struggled to see what was so bad about auto_ptr, after all, "it worked". It's a similar problem here. For the uninitiated, you are going to have to walk them through the baby steps to get their brain into the right gear to understand the point of the new primitive at all, and that takes time. I think you need that for 80-90% of potential Outcome users whom are not going to be familiar with expected<T, E> at all, you have no alternative but to provide a training course on why monadic value transports could add value to C++. For those who read the WG21 mailings regularly then LEWG's expected<T, E> is no surprise by now. It's pretty well understood, and the baby steps documentation is a waste of time for them. Instead that audience will surely raise an eyebrow on why a close alternative in Boost.Outcome is necessary when expected<T, E> is already heading for the C++ standard and there is an existing expected<T, E> reference library implementation. I think I need a second set of documentation for them too. Right now both sets of documentation are on the same page, and that is a mistake. I'll be splitting them up into two separate pages and making the front page much shorter and more of a "jumping off" summary page into the rest of the documentation.
I admit that I am a bit impatient, but this also might be an important feedback for you. I suppose, I am not the only impatient programmer that would be a potential user of your library, but may be discouraged by the documentation. It is clear that you have put a lot of effort into the documentation, but I still cannot find my way around it.
It starts with installation guide, then design rationale, then the history of error reporting in c++, then the long synopsis, and only at the end do we find an example, but it is quite complicated, and not quite well annotated, uses long names, and I am not even sure which names are part of boost::outcome, and which names are only invented for the sake of the example. I could only figure out that we have macro BOOST_OUTCOME_TRY <https://ned14.github.io/boost.outcome/monad_8hpp.html#aa977bf0b7aded30c781c35f956edc1d7>, which is a sort of control flow.
Really, some simple, annotated examples should be the first thing we see in the docs. In fact, there is a TODO at the top saying, "Add a vanilla use case snippet here". I would really like to see such example. For an example of what I mean, I recommend looking at the first pages of the documentation for Boost.Optional: http://www.boost.org/doc/libs/1_62_0/libs/optional/doc/html/index.html
That's a great suggestion. I'll mirror that example exactly. (BTW the todo's have been added based on feedback received here since I asked for feedback, they were not there originally).
Additionally, words "monad" and "monadic" appear quite often in the documentation. I fail to see how this is supposed to help understand the library. I am not familiar with FP, and this term distracts my efforts to understand what this library is for.
LEWG wants the monadic aspects of expected<T, E> to be split into a separate specification to be standardised later. Outcome has a much nicer and cleaner monadic operations API than expected<T, E>. Far easier and more fun to program with, but much heavier on the compiler because introspecting callables is currently slow in current compilers. I suspect a third documentation set is needed just for the functional programming crowd which is in a definite minority. I'll see what I can do. It's my lowest priority in the three sets of documentation. Many thanks for the feedback, very useful. Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/