Writing a Frameworks book at Randa

[Martin Gräßlin]

On Thursday 10 April 2014 01:42:13 Valorie Zimmerman wrote:
> On Thu, Apr 10, 2014 at 1:26 AM, Aurélien Gâteau <agateau at kde.org> wrote:
> > On Wed, Apr 9, 2014, at 6:05, Kevin Funk wrote:
> >> On Wednesday 09 April 2014 02:25:18 Valorie Zimmerman wrote:
> >> > Hello folks, I know that August is months away, but if you want your
> >> > Frameworks book, now is the time to step forward.
> >> > 
> >> > Here are some things to think about:
> >> > 
> >> > Most of this book is already written somewhere. When the words have
> >> > already been written down, all we need do is gather and arrange them.
> >> > When you think of such an email, dot story, blog post or have eloquent
> >> > thoughts in your head, please make a note.
> >> > 
> >> > If you are on this list, you are an expert. You know what the
> >> > Frameworks will do for KDE, and you know what they *can* do for
> >> > others. Our book will present that case. A good book will help grow
> >> > the Frameworks team; I'm sure of it. And a good book will make your
> >> > work more widely used. Oh, and you'll be a published author!
> >> > 
> >> > While in Randa, none of us will be writing full-time. In fact, I hope
> >> > that *all* of the Frameworks people will stop by the writing room, or
> >> > log into Booki and review, add, re-arrange, correct, or make the text
> >> > more graceful.
> >> > 
> >> > To make this work a few people must volunteer to take on the writing
> >> > of the book as their most important task at Randa. It will be mine,
> >> > and our goal is to have a book by the end of the week. We've done it
> >> > before, and I know we can do it again. This is a valuable work.
> >> > 
> >> > We need to know the core members of this team, soon. Please step
> >> > forward, and also add yourself to the Spints page for planning and
> >> > funding.
> >> > 
> >> > Valorie
> >> 
> >> Hey,
> >> 
> >> I'm wondering if we should rather try spending the time in making our KF5
> >> apidocs shine. You could spend plenty of time on writing introductory
> >> parts
> >> for the individual modules, writing tutorials and examples, and make sure
> >> they're easy to reach and grasp for newcomers on apidocs.kde.org. This is
> >> an
> >> integral part for the docs on qt-project.org, too. Just have a look at
> >> the
> >> first hit for "qt docs": [1]
> > 
> > I agree with this. I think api docs have a higher chance of remaining
> > relevant than a book.
> > 
> > Aurélien
> 
> There is no denying that apidox are crucially important. And I hope
> that some of what we write can contribute to that, perhaps. But I am
> in no way qualified to write those, while I am qualified to help this
> team write a book. Members of the team spoke up and felt that that was
> a useful thing to do.

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.

Cheers
Martin
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kde-frameworks-devel/attachments/20140410/23510951/attachment.sig>