Re: Writing a Frameworks book at Randa
Hi, On 05.05.2014 11:21, Valorie Zimmerman wrote: >> it would be great if you could make "remote participation" possible. While >> > it's too difficult for me to participate in the sprint directly I would be >> > able >> > to remote participate. >> > >> > Cheers >> > Martin > Excellent idea, Martin. I'll try to have instructions for those who > want to participate remotely all set up before we arrive in Randa. For > now, I hope people will start filling in the wiki page, and get ideas > percolating. > > Of course we will have IRC, but I hope it will be easy for people to > directly work on the book text from everywhere. I think I mentioned it before, but just to be sure - I am happy to join in effort this during Randa. As for getting more contributors to it, I suggest to have a look at booktype (http://www.sourcefabric.org/en/booktype/). Cheers, Mirko. -- Mirko Boehm | mi...@kde.org | KDE e.V. FSFE Fellow, FSFE Team Germany Qt Certified Specialist and Trainer ___ Kde-frameworks-devel mailing list Kde-frameworks-devel@kde.org https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
Re: Writing a Frameworks book at Randa
On Sun, May 4, 2014 at 1:33 AM, Martin Graesslin wrote: > On Saturday 03 May 2014 23:56:53 Valorie Zimmerman wrote: >> I know I said >> >> On Sat, May 3, 2014 at 2:14 AM, Valorie Zimmerman >> >> wrote: >> > Time is short, so this is the last time I'll write. Think about what >> > you want in your Frameworks book and commit to making it happen. >> > >> > Valorie >> > >> > 1. https://sprints.kde.org/sprint/212 >> >> but I think we have enough people signed up to to make this happen! >> Thanks to all of you who have stepped forward. > > it would be great if you could make "remote participation" possible. While > it's too difficult for me to participate in the sprint directly I would be > able > to remote participate. > > Cheers > Martin Excellent idea, Martin. I'll try to have instructions for those who want to participate remotely all set up before we arrive in Randa. For now, I hope people will start filling in the wiki page, and get ideas percolating. Of course we will have IRC, but I hope it will be easy for people to directly work on the book text from everywhere. Valorie -- http://about.me/valoriez ___ Kde-frameworks-devel mailing list Kde-frameworks-devel@kde.org https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
Re: Writing a Frameworks book at Randa
On Saturday 03 May 2014 23:56:53 Valorie Zimmerman wrote: > I know I said > > On Sat, May 3, 2014 at 2:14 AM, Valorie Zimmerman > > wrote: > > Time is short, so this is the last time I'll write. Think about what > > you want in your Frameworks book and commit to making it happen. > > > > Valorie > > > > 1. https://sprints.kde.org/sprint/212 > > but I think we have enough people signed up to to make this happen! > Thanks to all of you who have stepped forward. it would be great if you could make "remote participation" possible. While it's too difficult for me to participate in the sprint directly I would be able to remote participate. 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
Re: Writing a Frameworks book at Randa
On Thursday 24 April 2014 02:24:05 Valorie Zimmerman wrote: > > I was excited to hear David Narvaez' ideas about what the book should > be. It sounds like the focus is happening. However, not many people > have committed to come to Randa and get this book started. > > Right now there is one person on https://sprints.kde.org/sprint/212 > listing kdebooks as their task. I can ask other people to come to > Randa to help shape the text, but we *must* have Frameworks people > committed to this project to make it happen. > > The deadline for signing up is approaching. Please sign up now if you > intend to come to write. The e.V. and other funders will support us if > we step up; but I will not waste their money by flying to Switzerland > without a committed group of writers. While working on Inqlude I realized that the presentation of the framework still needs a lot of love. A book could be a great part of that. I would hope for something which gets people started, provides them the entry points and background they need, and contains some practical examples how to work with the frameworks. Especially examples could also get a life on their own and be maintained and used beyond the book as introduction for people starting to use the frameworks. I would be happy to help with this effort and will sign up for the meeting now. -- Cornelius Schumacher ___ Kde-frameworks-devel mailing list Kde-frameworks-devel@kde.org https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
Re: Re: Writing a Frameworks book at Randa
I know I said On Sat, May 3, 2014 at 2:14 AM, Valorie Zimmerman wrote: > Time is short, so this is the last time I'll write. Think about what > you want in your Frameworks book and commit to making it happen. > > Valorie > > 1. https://sprints.kde.org/sprint/212 but I think we have enough people signed up to to make this happen! Thanks to all of you who have stepped forward. I've created a wiki page here: http://community.kde.org/KDE_Documentation/KdeBooks#KDE_Books to begin gathering ideas/recipes. As you have thoughts and ideas, whether or not you'll be attending, write them up, please. Of course we'd like to have possible 'problems which can be solved by a framework or two' for each of the frameworks. We want ALL the ideas now, and pick and choose only the best for our book. Write out your idea even if it seems weak -- it might spark an idea for someone else. Valorie -- http://community.kde.org/KDE_Documentation/KdeBooks#KDE_Books ___ Kde-frameworks-devel mailing list Kde-frameworks-devel@kde.org https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
Re: Re: Writing a Frameworks book at Randa
On Thu, Apr 10, 2014 at 9:23 PM, David Narvaez wrote: > On Thu, Apr 10, 2014 at 5:02 AM, Martin Gräßlin wrote: >> 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. > > I have been thinking these are two orthogonal things. These are > thoughts I had when this idea was first posted and may be relevant to > this current discussion: > > O'Reilly media has these series of cookbooks. So you have > > * Programming in Perl[0]: " Programming Perl, hit the shelves in 1990, > and was quickly adopted as the undisputed bible of the language" > * Perl Cookbook[1]: "The Perl Cookbook is a comprehensive collection > of problems, solutions, and practical examples for anyone programming > in Perl." > > I would presonally like us to have a Frameworks Cookbook after Randa, > not a Frameworks Bible. Those bible textbooks are the ones that > deprecate next month, that are always racing with apidocs and that > never actually cover every possible thing a library has to offer. > Cookbooks, on the other hand, go straight to the point of solving > concrete problems, and while specific code snippets may end up being > deprecated in time, the idea of "I can solve this problem by mashing > up these 3 frameworks" will be essentially valid for a longer time. > > Plus, I think the cool idea of Frameworks is that they are useful for > general problem solving, so lets market them using real problems. If > people like this idea, then we can spend some time coming up with > problems you can solve using Frameworks and then take (pre?-)Randa > time to solve them, then write those solutions in the book. > > David E. Narvaez > > [0] http://shop.oreilly.com/product/9780596000271.do > [1] http://shop.oreilly.com/product/9781565922433.do I used to bake bread for the family as fast as we ate it. I had a grain grinder and got raw milk, so there was fresh butter to put on that hot-from-the-oven whole wheat bread! It makes my mouth water to remember the smell of the bread as the kids broke that first loaf into pieces, when it was too hot to slice. What made that bread delicious were good ingredients, some work, and time. Bread can't be made without flour, liquid, yeast, salt, kneading, and time rising, and baking. I was happy to see that Cornelius has registered for the Randa sprint [1] and put at his first task, writing the book. We need a couple more people to sign up, or add KDEbooks as a secondary task, to knead and bake ourselves a wonderful book. Time is short, so this is the last time I'll write. Think about what you want in your Frameworks book and commit to making it happen. Valorie 1. https://sprints.kde.org/sprint/212 -- http://about.me/valoriez ___ Kde-frameworks-devel mailing list Kde-frameworks-devel@kde.org https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
Re: Re: Re: Writing a Frameworks book at Randa
On Sun, Apr 13, 2014 at 10:38 PM, Martin Gräßlin wrote: > On Friday 11 April 2014 00:23:26 David Narvaez wrote: >> On Thu, Apr 10, 2014 at 5:02 AM, Martin Gräßlin wrote: >> > 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. >> >> I have been thinking these are two orthogonal things. These are >> thoughts I had when this idea was first posted and may be relevant to >> this current discussion: >> >> O'Reilly media has these series of cookbooks. So you have >> >> * Programming in Perl[0]: " Programming Perl, hit the shelves in 1990, >> and was quickly adopted as the undisputed bible of the language" >> * Perl Cookbook[1]: "The Perl Cookbook is a comprehensive collection >> of problems, solutions, and practical examples for anyone programming >> in Perl." >> >> I would presonally like us to have a Frameworks Cookbook after Randa, >> not a Frameworks Bible. > > Fully agree and that's what I hoped the book would be about. But it's > something which requires domain knowledge. E.g. examples for KWindowSystems > need someone to really know what the framework is doing to just come up with a > good idea for such a recipe. > > I wouldn't mind to collect ideas and solutions over the time, but it's too > late to do it at the sprint. > > Cheers > Martin I was excited to hear David Narvaez' ideas about what the book should be. It sounds like the focus is happening. However, not many people have committed to come to Randa and get this book started. Right now there is one person on https://sprints.kde.org/sprint/212 listing kdebooks as their task. I can ask other people to come to Randa to help shape the text, but we *must* have Frameworks people committed to this project to make it happen. The deadline for signing up is approaching. Please sign up now if you intend to come to write. The e.V. and other funders will support us if we step up; but I will not waste their money by flying to Switzerland without a committed group of writers. Valorie -- http://about.me/valoriez ___ Kde-frameworks-devel mailing list Kde-frameworks-devel@kde.org https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
Re: Re: Re: Writing a Frameworks book at Randa
On Friday 11 April 2014 00:23:26 David Narvaez wrote: > On Thu, Apr 10, 2014 at 5:02 AM, Martin Gräßlin wrote: > > 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. > > I have been thinking these are two orthogonal things. These are > thoughts I had when this idea was first posted and may be relevant to > this current discussion: > > O'Reilly media has these series of cookbooks. So you have > > * Programming in Perl[0]: " Programming Perl, hit the shelves in 1990, > and was quickly adopted as the undisputed bible of the language" > * Perl Cookbook[1]: "The Perl Cookbook is a comprehensive collection > of problems, solutions, and practical examples for anyone programming > in Perl." > > I would presonally like us to have a Frameworks Cookbook after Randa, > not a Frameworks Bible. Fully agree and that's what I hoped the book would be about. But it's something which requires domain knowledge. E.g. examples for KWindowSystems need someone to really know what the framework is doing to just come up with a good idea for such a recipe. I wouldn't mind to collect ideas and solutions over the time, but it's too late to do it at the sprint. 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
Re: Re: Writing a Frameworks book at Randa
On Thu, Apr 10, 2014 at 5:02 AM, Martin Gräßlin wrote: > 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. I have been thinking these are two orthogonal things. These are thoughts I had when this idea was first posted and may be relevant to this current discussion: O'Reilly media has these series of cookbooks. So you have * Programming in Perl[0]: " Programming Perl, hit the shelves in 1990, and was quickly adopted as the undisputed bible of the language" * Perl Cookbook[1]: "The Perl Cookbook is a comprehensive collection of problems, solutions, and practical examples for anyone programming in Perl." I would presonally like us to have a Frameworks Cookbook after Randa, not a Frameworks Bible. Those bible textbooks are the ones that deprecate next month, that are always racing with apidocs and that never actually cover every possible thing a library has to offer. Cookbooks, on the other hand, go straight to the point of solving concrete problems, and while specific code snippets may end up being deprecated in time, the idea of "I can solve this problem by mashing up these 3 frameworks" will be essentially valid for a longer time. Plus, I think the cool idea of Frameworks is that they are useful for general problem solving, so lets market them using real problems. If people like this idea, then we can spend some time coming up with problems you can solve using Frameworks and then take (pre?-)Randa time to solve them, then write those solutions in the book. David E. Narvaez [0] http://shop.oreilly.com/product/9780596000271.do [1] http://shop.oreilly.com/product/9781565922433.do ___ Kde-frameworks-devel mailing list Kde-frameworks-devel@kde.org https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
Re: Re: Writing a Frameworks book at Randa
On Thursday 10 April 2014 01:42:13 Valorie Zimmerman wrote: > On Thu, Apr 10, 2014 at 1:26 AM, Aurélien Gâteau 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
Re: Writing a Frameworks book at Randa
On Thu, Apr 10, 2014 at 1:26 AM, Aurélien Gâteau 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. Obviously the audience we'd write for would be heading for the apidox once they got interested enough to investigate the frameworks for their projects. A book can only be introductory, for the reasons you all have stated. Valorie -- http://about.me/valoriez ___ Kde-frameworks-devel mailing list Kde-frameworks-devel@kde.org https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
Re: Writing a Frameworks book at Randa
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 ___ Kde-frameworks-devel mailing list Kde-frameworks-devel@kde.org https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
Re: Writing a Frameworks book at Randa
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 ___ Kde-frameworks-devel mailing list Kde-frameworks-devel@kde.org https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
Re: Writing a Frameworks book at Randa
On Wednesday 09 April 2014 15:42:47 Aleix Pol wrote: > On Wed, Apr 9, 2014 at 3:05 PM, 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] > > > > 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. 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 anyo
Re: Writing a Frameworks book at Randa
On Wed, Apr 9, 2014 at 3:05 PM, 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] > > 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
Re: Writing a Frameworks book at Randa
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
