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

Subject: Re: [boost] [outcome] Requesting second pre-review of Boost.Outcome tutorial
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-01-26 12:28:59

On 1/26/17 2:05 AM, Niall Douglas wrote:

>> I'm gratified that you've taken the task of documentation as an integral
>> part of developing the library.  I've been flogging this idea in the
>> boost incubator.  I've got a lot to say about this there.
>
> 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.
>
> Still, as you would say Robert, that's the price of good documentation.

** warning ** off topic rant you've probably been exposed to before. TL;DR
I think you're feelings about writing documentation are widely shared. 
And I think this is big problem for everyone.

It works well for me to write the tutorial while I'm writing the code. 
I go back and forth between example, reference and code more or less at 
whim.  I think of the tutorial and reference are aspects of the code. 
The reference is basically a form filling exercise - concepts, types and 
free functions.  The code is types and free functions.  When I start 
coding I don't really plan much - it's sort of free form.  I write some 
code and write an example to be able to compile it.  I have to do this 
because it's header only code.  When I think I like it, I add the 
tutorial narrative and fill out the type/function form.  Of course at 
this point I discover a lot of errors.  Often the concepts need to be 
shuffled around, and this ripples through the code.  At this point, it's 
still a small project so this isn't too painful.  I've now convinced 
myself that this is going to be easy - all I have to do is add a few 
more examples and make sure they work.  Of course this an illusion. 
Like I'm just going to pull this one loose thread out of my sweater. 
BUT I do have one thing "done" so I can't throw away my "finished" work 
and I'm motivated to push on.

For this to work one needs to have a painless way to make documentation 
as one proceeds without having to get sucked into a lot issues like 
presentation, organization, etc, etc.  For me Boost Book has worked for 
me to isolate me from this "noise".  I have great tool for editing boost 
book with a wysiwyg editor so it's quite painless.  It's really part of 
tool setup.  IDE for code, BoostBook/XMLMind for documentation, Git for 
revision control of both the code and documetation.  They are always in 
sync and I can go back, branch etc.  The only really weakspot and source 
of pain is CMake/b2 which always cause problems.

Normally programmers write all the code and then try to document it. 
This is agonizingly tedious. In practice, the documentation ends up as 
an after thought is is out of sync with the code - and it shows.  Also 
writing the docs and tutorials always reveals problems in the library 
design.  But now it's so late in the process and the ripple effect is so 
large, it's just to painful to fix and we just say "good enough".  I 
spent too much time on this already.  This probably explains why 99% of 
"open source" code has not documentation at all.

Robert Ramey

>
> Niall
>
>