[boost] Re: MPL documentation

From: David Abrahams (dave_at_[hidden])
Date: 2004-11-23 09:37:56

"Edward Diener" <eddielee_at_[hidden]> writes:

>>From these topics I would guess that a good overview before your chapter 3
> would entail a basic explanation of:
>
> 1.4.1
> 1.4.2
> 2.2
> 2.3
> 2.6
> 2.7

That looks good.

> and anything related to them regarding values and types you want to say. I
> would leave out all but the simplest examples showing exactly what you mean
> and just explain the ideas.

That's what we thought we were doing in the book!  ;-)
Concision is hard.

> What I am simple saying is that if you want to make it fairly easy for the
> non-experienced MPL programmer to pick up the MPL library you will include
> some material about the information above. I could even say to you, although
> it is purely your and Mr. Gurtovoy's choice, that you might think of making
> chapters 1 and 2 available online as you have chapter 3. 

It's not up to us; Addison-Wesley owns the material and I doubt
they'd be willing to let us do that.

> Of course you may well feel that by doing this you are giving away
> what you feel you should earn via book sales, as well it may be that
> your book contract does not allow this anyway.

Bingo.

> I do think that it is possible to understand your MPL library
> without the information in chapters 1 and 2, but that it becomes
> more difficult, and more work, for the beginning MPL programmer to
> do so.

I agree.

> Personally I get discouraged when documentation does not give me a good
> overview of concepts, not because I think that I can not pick up the
> information if I were willing to investigate and work at it but because I
> get annoyed that those who are doing good work are not providing me with the
> information I need to make learning easier. 

It is reasonable to expect the basic concepts to be defined.

> Perhaps I am not in the majority, but my view of the importance of
> good documentation is not that of the majority either. I realize
> that both you and Mr. Gurtovy may be tired of explaining MPL now
> that you have written a book about it, and documented it in the
> Boost MPL reference, to write anything more. 

I little.

> I can only say to you that you put yourself in the place of
> programmers who may be interested in your ideas, who are
> intelligent, who follow the Boost libraries, but do not know what
> you do about metaprogramming and how you designed the library to
> make it easier for people to metaprogramming in C++. If you think
> you have given enough, fine. 

If you include the book, I think we have.  But I do think the website
needs to cover a few of the basic concepts we've left out.  I even
think it would help book sales to include more information.

> If not, consider one more effort at a basic number of pages of
> introduction, perhaps very few in number and very basic, which leads
> programmers to be interested in your ideas. Thanks for listening !

Whew.  I wonder when there will be time?

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com