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

Subject: Re: [Boost-users] [Phoenix] Review: Documentation
From: Joel de Guzman (joel_at_[hidden])
Date: 2008-09-30 00:28:40

Roland Bock wrote:
> 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.

Ok, I'll try to provide more background.

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

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

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.

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

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?

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

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

Regards,
-- 
Joel de Guzman
http://www.boostpro.com
http://spirit.sf.net