<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Wed, Apr 9, 2014 at 3:05 PM, Kevin Funk <span dir="ltr"><<a href="mailto:kfunk@kde.org" target="_blank">kfunk@kde.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div class=""><div class="h5">On Wednesday 09 April 2014 02:25:18 Valorie Zimmerman wrote:<br>
> Hello folks, I know that August is months away, but if you want your<br>
> Frameworks book, now is the time to step forward.<br>
><br>
> Here are some things to think about:<br>
><br>
> Most of this book is already written somewhere. When the words have<br>
> already been written down, all we need do is gather and arrange them.<br>
> When you think of such an email, dot story, blog post or have eloquent<br>
> thoughts in your head, please make a note.<br>
><br>
> If you are on this list, you are an expert. You know what the<br>
> Frameworks will do for KDE, and you know what they *can* do for<br>
> others. Our book will present that case. A good book will help grow<br>
> the Frameworks team; I'm sure of it. And a good book will make your<br>
> work more widely used. Oh, and you'll be a published author!<br>
><br>
> While in Randa, none of us will be writing full-time. In fact, I hope<br>
> that *all* of the Frameworks people will stop by the writing room, or<br>
> log into Booki and review, add, re-arrange, correct, or make the text<br>
> more graceful.<br>
><br>
> To make this work a few people must volunteer to take on the writing<br>
> of the book as their most important task at Randa. It will be mine,<br>
> and our goal is to have a book by the end of the week. We've done it<br>
> before, and I know we can do it again. This is a valuable work.<br>
><br>
> We need to know the core members of this team, soon. Please step<br>
> forward, and also add yourself to the Spints page for planning and<br>
> funding.<br>
><br>
> Valorie<br>
<br>
</div></div>Hey,<br>
<br>
I'm wondering if we should rather try spending the time in making our KF5<br>
apidocs shine. You could spend plenty of time on writing introductory parts<br>
for the individual modules, writing tutorials and examples, and make sure<br>
they're easy to reach and grasp for newcomers on <a href="http://apidocs.kde.org" target="_blank">apidocs.kde.org</a>. This is an<br>
integral part for the docs on <a href="http://qt-project.org" target="_blank">qt-project.org</a>, too. Just have a look at the<br>
first hit for "qt docs": [1]<br>
<br>
There's a "Getting Started" section, with overviews [2] with examples and<br>
tutorials [3]. That's *exactly* what we need for KF5, too. That's the best<br>
place to point newcomers to whenever they want to get wet with KF5. But it<br>
also takes time and people to get to this state.<br>
<br>
Personally, from a developer POV, I don't really see the need for a separate<br>
"book". There will always be a discrepancy between the book and the actual<br>
code (be it completeness, accuracy, its up-to-date-ness), and for developers<br>
it's always an extra burden to make sure to amend the contents of the book<br>
whenever they change something in source code. It's much more straight-forward<br>
to make sure that at least the apidocs are up-to-date. The apidocs being<br>
inline in the source code being is an integral part in making sure they're<br>
amended alongside of source code changes.<br>
<br>
Opinions? What do the frameworks devs think about it?<br>
<br>
Greets<br>
<br>
[1] <a href="http://qt-project.org/doc/qt-5/index.html" target="_blank">http://qt-project.org/doc/qt-5/index.html</a><br>
[2] <a href="http://qt-project.org/doc/qt-5/overviews-main.html" target="_blank">http://qt-project.org/doc/qt-5/overviews-main.html</a><br>
[3] <a href="http://qt-project.org/doc/qt-5/qtexamplesandtutorials.html" target="_blank">http://qt-project.org/doc/qt-5/qtexamplesandtutorials.html</a><br>
<span class=""><font color="#888888"><br>
--<br>
Kevin Funk<br>
</font></span><div class=""><div class="h5">_______________________________________________<br>
Kde-frameworks-devel mailing list<br>
<a href="mailto:Kde-frameworks-devel@kde.org">Kde-frameworks-devel@kde.org</a><br>
<a href="https://mail.kde.org/mailman/listinfo/kde-frameworks-devel" target="_blank">https://mail.kde.org/mailman/listinfo/kde-frameworks-devel</a><br>
</div></div></blockquote></div><br></div><div class="gmail_extra">Hi,</div><div class="gmail_extra">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.</div>
<div class="gmail_extra"><br></div><div class="gmail_extra">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.</div>
<div class="gmail_extra">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.<br></div><div class="gmail_extra"><br>
</div><div class="gmail_extra">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.</div><div class="gmail_extra"><br>
</div><div class="gmail_extra">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.</div><div class="gmail_extra">
<br></div><div class="gmail_extra">Aleix</div><div class="gmail_extra"><br></div><div class="gmail_extra">[1] <a href="http://techbase.kde.org/Welcome_to_KDE_TechBase">http://techbase.kde.org/Welcome_to_KDE_TechBase</a></div>
</div>