Re: [Boost-users] [Phoenix] Review: Documentation

Subject: Re: [Boost-users] [Phoenix] Review: Documentation
From: Roland Bock (rbock_at_[hidden])
Date: 2008-09-30 03:28:13

Hi Joel,

Joel de Guzman wrote:
>> For example, the actor's page. It says that it is the main concept and 
>> it shows a template and with one parameter, which does not appear 
>> anywhere near the template's body. And that's pretty much it. It does 
>> not say anything about when it is used, by whom, or what the necessary 
>> characteristics of the template argument "Eval" are. Nothing. Except:
>> "Don't worry about the details, for now."
> 
> And at that point, it's certainly the case. It's just short of saying
> that, hey, you need to know about this class, but not in detail.
> The details will be discussed later.

Well, maybe then it is even too much to show the template code? I admit, 
I was staring at it, wondering what it might tell me.

> Yes, and that's all you need to know at that point. More detail
> will be provided in subsequent sections. Providing the details
> at this point, IMO, would distract from the main subject matter.

OK, my point is that I fail to see what the main subject matter is on 
that page. I promise to learn more about FP and instead of saying "This 
could be better", I will try to come up with contribution to the 
documentation.

> The least I could do, perhaps, is to provide links to other parts
> in the doc where these are explained in detail, for those who
> are itching to know more. Is that an acceptable solution?

Sounds good to me :-)

> To be honest, it will be hard to find examples that would please
> everyone, but you have a good point and I'll try to find a
> sweet set of examples beyond the "First Practical Example".

Great! Maybe I develop useful examples on my own while learning more 
about FP. If so, I am going to share them, of course.

Thanks for your efforts!

Regards,

Roland