[Boost-users] [Phoenix] Review: Documentation

Subject: [Boost-users] [Phoenix] Review: Documentation
From: Roland Bock (rbock_at_[hidden])
Date: 2008-09-29 16:20:25

Hi,

regarding the Phoenix documentation: I'm afraid you lost me not too far 
from the beginning, and I would like to remark a few things:

Details:
========
I am missing details and/or background, maybe even just a sentence or 
two more, here and there. I assume that for library designers and FP 
experts most of the things are crystal clear anyways. But for laymen 
like me, some things are pretty obscure.

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."

Sorry, but you lost me there. I do not have the lightest idea of what an 
actor is all about after reading this page. This certainly leaves a bad 
feeling, because the one clear statement on the page is "The Actor is 
the main concept behind the library."

Not to worry about details would normally help to focus on the important 
stuff, the central concept, the main thought. But in this case? I am 
just being told that the actor is in fact the main concept.

I don't know if all the gory details are required on that page, maybe 
there are too many details already (the template's code). I cannot tell. 
But I know that the concepts/ideas for this thing need to be explained 
before going on.

In contrast to a crime story, I would prefer to know the plot before 
going on. When meeting one of the main characters, I do not want to get 
to know him along with the story. No, I would learn about the 
characteristics right away and decide whether I want to spend more time 
reading about him (or using him in one of my projects).

I cannot really tell if the following things are documented in enough 
detail, since I guess I need to understand the concept of the actor. I 
am afraid, though, that I would require a few more sentences, here and 
there, or maybe just a few more examples.

Examples:
=========
IMHO, most examples are either too simple or too abstract.

For example:
The "real world example" from the starter kit is not really a real world 
example, it is too simple. So don't throw it away, but add something a 
little bit more complex. For instance, you could combine it with one 
from the composite page (which is pretty abstract in my eyes and does 
not tell me anything):

///////////////
struct A
{
     int member;
};

A* a = new A;
...

(arg1->*&A::member)(a); // returns member a->member
///////////////

You could use this in the "real world example". Replace vector<int> by 
vector<A> and then find objects with object.member%2==1. I assume that 
would help me.

Regards,

Roland