Writing a Frameworks book at Randa

[Kevin Funk]

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]

There's a "Getting Started" section, with overviews [2] with examples and 
tutorials [3]. That's *exactly* what we need for KF5, too. That's the best 
place to point newcomers to whenever they want to get wet with KF5. But it 
also takes time and people to get to this state.

Personally, from a developer POV, I don't really see the need for a separate 
"book". There will always be a discrepancy between the book and the actual 
code (be it completeness, accuracy, its up-to-date-ness), and for developers 
it's always an extra burden to make sure to amend the contents of the book 
whenever they change something in source code. It's much more straight-forward 
to make sure that at least the apidocs are up-to-date. The apidocs being 
inline in the source code being is an integral part in making sure they're 
amended alongside of source code changes.

Opinions? What do the frameworks devs think about it?

Greets

[1] http://qt-project.org/doc/qt-5/index.html
[2] http://qt-project.org/doc/qt-5/overviews-main.html
[3] http://qt-project.org/doc/qt-5/qtexamplesandtutorials.html

-- 
Kevin Funk