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

Subject: Re: [boost] [outcome] Requesting pre-review of Boost.Outcome tutorial
From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2016-11-22 03:34:45

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/