On Thursday 10 April 2014 01:42:13 Valorie Zimmerman wrote: > On Thu, Apr 10, 2014 at 1:26 AM, Aurélien Gâteau <agat...@kde.org> wrote: > > On Wed, Apr 9, 2014, at 6:05, Kevin Funk 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] > > > > I agree with this. I think api docs have a higher chance of remaining > > relevant than a book. > > > > Aurélien > > There is no denying that apidox are crucially important. And I hope > that some of what we write can contribute to that, perhaps. But I am > in no way qualified to write those, while I am qualified to help this > team write a book. Members of the team spoke up and felt that that was > a useful thing to do.
we might have here a chicken-egg problem. Good API documentation would significantly help for writing the book. That is if the API documentation is good someone without deep domain knowledge will be able to write a book about it. But if the API documentation is not good enough it needs domain knowledge to write those. Now what I read out of the thread is that developers think that the time of the domain experts would be better spent writing the API documentation than writing a book. The question now is whether our API documentation is already good enough to write a book without domain experts or if we need to improve the documentation first, whether we could do this at the sprint instead of (or in addition) to writing a book. Cheers Martin
signature.asc
Description: This is a digitally signed message part.
_______________________________________________ Kde-frameworks-devel mailing list Kde-frameworks-devel@kde.org https://mail.kde.org/mailman/listinfo/kde-frameworks-devel