Writing a Frameworks book at Randa

Wed Apr 9 15:26:11 UTC 2014

On Wednesday 09 April 2014 15:42:47 Aleix Pol wrote:
> On Wed, Apr 9, 2014 at 3:05 PM, Kevin Funk <kfunk at kde.org> 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]
> > 
> > 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
> > _______________________________________________
> > Kde-frameworks-devel mailing list
> > Kde-frameworks-devel at kde.org
> > https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
> 
> Hi,
> I'm unsure what to say. On one hand, people always seem inclined to have
> some literature available, especially in the shape of a book. It helps you
> go through the technologies when you don't know much what you're doing but
> you still want to learn. It offers a linear overview of interesting things
> on a related subject, meaning that if things are not interesting, you can
> opt to not include them in the book.
> 
> On the other hand, documentation is much more future-proof in terms of
> having it actively-ish maintained and it will be more useful for the
> developers who decide to stay using KF5, since they will know what to look
> for.
> A proof of this is that even though we have wonderful Qt documentation, we
> see new books appearing all the time, and I guess this means they pay off,
> at least.
> 
> Maybe we should consider the book more as a replacement to the TechBase
> [1], if it's even possible to offer it in a proper web shape as well, at
> least.
> 
> Personally, given that there will be compromises either way, I would say
> that who codes (or writes) decides. I'll be happy to give a hand in either
> direction.

Fair point. Regardless of what we do, it will be an improvement.

>From my point of view, proper API documentation/tutorials should be given 
primary focus, though, given the lack of manpower in this area. Don't get me 
wrong, I don't want to demotivate anyone from this kind of documentation work 
(be it in form of a book or apidocs). I'm happy to see it emerge either way. 
Aleix nails it, whoever does the work, decides.

My worry is just that people spend a lot of time on polishing a book (which 
the average user won't conduct) but neglect the presentation of KF5 on 
api.kde.org (which *is* the first point of contact for the average user).

Please note, I'm not saying noone will read that book, it's just that the book 
alone won't really help people who *are already* working very closely with 
KF5. Us, as in "the people hacking on KDE".

I'll likely be part of the Randa sprint, too, so I can give a hand as well.

> Aleix
> 
> [1] http://techbase.kde.org/Welcome_to_KDE_TechBase

Greets

-- 
Kevin Funk