On Wed, Apr 9, 2014 at 3:05 PM, Kevin Funk <kf...@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@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. Aleix [1] http://techbase.kde.org/Welcome_to_KDE_TechBase
_______________________________________________ Kde-frameworks-devel mailing list Kde-frameworks-devel@kde.org https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
