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

Subject: Re: [boost] [outcome] Requesting second pre-review of Boost.Outcome tutorial
From: Hans Dembinski (hans.dembinski_at_[hidden])
Date: 2017-01-27 04:45:38

> On 1/26/17 2:05 AM, Niall Douglas wrote:
> 
>> I would more describe it as a cross to carry whilst being whipped on the
>> road to Golgotha. Lucky I'm Catholic. I'm reaching the point where I'd
>> prefer a broken arm to rewriting the damn tutorial yet again, the fact
>> people need stuff spelled out to them in such incremental and precise
>> detail and can't just mentally fill in the very obvious small gaps I
>> find extremely frustrating.

:) I think we can all feel with you. Nevertheless, I think writing tutorials is a useful way to get into the user's head. For some reason, it is very hard to put yourself in the shoe of the novice once you understood something. That's universally true for everyone. We also need to accept that some people pick up things up faster and others slower. There are simply vastly different levels of experience out there.

Everything is easy once you mentally embraced it, but we need to remember how we felt when we tried to learn a new library and what helped us most. It can also help with realising flaws in the design of the user interface, as Robert pointed out.

I like what the Zen of Python has to say about this:
"If the implementation is hard to explain, it's a bad idea."
"If the implementation is easy to explain, it may be a good idea."

I would replace "implementation" with "interface", because we usually allow the implementation to be more messy and complicated, but the user-visible part at least should be intuitive and consistent.

Hans