[boost] Re: FC++: formal review

From: Matthew Vogt (mvogt_at_[hidden])
Date: 2004-03-01 18:31:32

Joel de Guzman <joel <at> boost-consulting.com> writes:

> When reviewing a language (yes, FC++ *is* a language, or more particularly,
> an EDSL--embedded domain specific language; sure Spirit is also an EDSL), 

<snip>

> * What is your evaluation of the documentation?
> 
>    In a word: poor. However, I'm sure the author(s) are aware of this and
>    I'm sure we'll see better documentaion in the future.
> 
>    Examples speak volumes. I'd like to see more fully commented or annotated
>    client applications and examples from the simple to the complex preferably
>    hooked into the documentation.
> 
>    Tutorials. I'd like to see a tutorial that hand-holds a would be user
>    into the FC++ realm.
> 

I would choose the word 'misdirected'.  I just had the pleasure to read the 
spirit user's guide front-to-back on the weekend, and as a C++ programmer with
very little knowledge of the field of parsing, I found it to be very attuned
to my learning curve. 

The documentation in FC++ on the other hand is directed more at programmers
who understand the functional programming domain, and now want to apply
those concepts in C++.  Thus, it didn't really help me identify situations
where I would benefit from FC++, and therefore didn't hold my interest through
the necesary detail learning phase.

(Aside: why is FC++ targetted the way it is?  Why are Haskell programmers 
migrating to C++ anyway?  Or is this the wrong conclusion to draw?)

I don't think that it's tutorials that are required so much, but motivating 
examples.  I think most C++ programmers come to boost from imperative 
programming, and it's great to find support in boost for alternative ways of
doing things.  But documentation for those methods must take the viewpoint
that they are introducing alternative methods to C++ programmers in order to 
be effective.

All that aside, misdirected documentation will merely consign FC++ to 
(relative) obscurity - if the functionality and implementation are of the
desired quality, those who already understand the paradigm will derive benefit
from its acceptance into boost.

Matt