Writing a Frameworks book at Randa

[Mario Fux]

Am Mittwoch, 09. April 2014, 15.05:06 schrieb Kevin Funk:

Morning Valorie, Kevin and Co

Thanks for bringing this topic up again.

> 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.

+1 from my side here ;-).

About the book. I think the first one was quite a success and often used to 
direct new people, contributors to. And IIRC you (Valorie) and Co took care 
not to integrate information in the book that was in heavy flux and often 
changed.

So it mostly a beginners guide for KDE Platform and soon KF5 users, a bigger 
brochure that helps to get a broad overview.

For the frameworks people that already registered on 
sprints.kde.org/sprint/212 please put some time aside to get to Valorie and Co 
in Randa and have a look or two and a helping hand.

> > 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?

There is one above. And about the apidocs and examples and online resources I 
agree. They are important, very important and probably sometimes even more 
important than a book. But I think both are valuable and both have target 
groups.

The questions is probably more. Would a dedicated KF5 apidocs meeting or 
sprint be of value?

Another idea from my side is to include the kde-doc people in this effort and 
discussion?

> 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

Thanks and best regards
Mario