Writing a Frameworks book at Randa

[David Narvaez]

On Thu, Apr 10, 2014 at 5:02 AM, Martin Gräßlin <mgraesslin at kde.org> wrote:
> we might have here a chicken-egg problem. Good API documentation would
> significantly help for writing the book. That is if the API documentation is
> good someone without deep domain knowledge will be able to write a book about
> it. But if the API documentation is not good enough it needs domain knowledge
> to write those.
>
> Now what I read out of the thread is that developers think that the time of
> the domain experts would be better spent writing the API documentation than
> writing a book.
>
> The question now is whether our API documentation is already good enough to
> write a book without domain experts or if we need to improve the documentation
> first, whether we could do this at the sprint instead of (or in addition) to
> writing a book.

I have been thinking these are two orthogonal things. These are
thoughts I had when this idea was first posted and may be relevant to
this current discussion:

O'Reilly media has these series of cookbooks. So you have

* Programming in Perl[0]: " Programming Perl, hit the shelves in 1990,
and was quickly adopted as the undisputed bible of the language"
* Perl Cookbook[1]: "The Perl Cookbook is a comprehensive collection
of problems, solutions, and practical examples for anyone programming
in Perl."

I would presonally like us to have a Frameworks Cookbook after Randa,
not a Frameworks Bible. Those bible textbooks are the ones that
deprecate next month, that are always racing with apidocs and that
never actually cover every possible thing a library has to offer.
Cookbooks, on the other hand, go straight to the point of solving
concrete problems, and while specific code snippets may end up being
deprecated in time, the idea of "I can solve this problem by mashing
up these 3 frameworks" will be essentially valid for a longer time.

Plus, I think the cool idea of Frameworks is that they are useful for
general problem solving, so lets market them using real problems. If
people like this idea, then we can spend some time coming up with
problems you can solve using Frameworks and then take (pre?-)Randa
time to solve them, then write those solutions in the book.

David E. Narvaez

[0] http://shop.oreilly.com/product/9780596000271.do
[1] http://shop.oreilly.com/product/9781565922433.do