Writing a Frameworks book at Randa

[Valorie Zimmerman]

On Thu, Apr 10, 2014 at 9:23 PM, David Narvaez
<david.narvaez at computer.org> wrote:
> 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

I used to bake bread for the family as fast as we ate it. I had a
grain grinder and got raw milk, so there was fresh butter to put on
that hot-from-the-oven whole wheat bread! It makes my mouth water to
remember the smell of the bread as the kids broke that first loaf into
pieces, when it was too hot to slice.

What made that bread delicious were good ingredients, some work, and
time. Bread can't be made without flour, liquid, yeast, salt,
kneading, and time rising, and baking.

I was happy to see that Cornelius has registered for the Randa sprint
[1] and put at his first task, writing the book. We need  a couple
more people to sign up, or add KDEbooks as a secondary task, to knead
and bake ourselves a wonderful book.

Time is short, so this is the last time I'll write. Think about what
you want in your Frameworks book and commit to making it happen.

Valorie

1. https://sprints.kde.org/sprint/212
-- 
http://about.me/valoriez