Wednesday, August 13, 2014

The Book

When inviting to the Randa 2014 meeting, Mario had the idea to write a book about KDE Frameworks. Valorie picked up this idea and kicked off a small team to tackle the task. So in the middle of August, Valorie, Rohan, Mirko, Bruno, and me gathered in a small room under the roof of the Randa house and started to ponder how to accomplish writing a book in the week of the meeting. Three days later and with the help of many others, Valorie showed around the first version of the book on her Kindle at breakfast. Mission accomplished.


Mission accomplished is a bit of an exaggeration, as you might have suspected. While we had a first version of the book, of course there still is a lot to be added, more content, more structure, more beautiful appearance. But we had quickly settled on the idea that the book shouldn't be a one-time effort, but an on-going project, which grows over time, and is continuously updated as the Frameworks develop, and people find the time and energy to contribute content.

So in addition to writing initial content we spend our thoughts and work on setting up an infrastructure, which will support a sustained effort to develop and maintain the book. While there will come more, having the book on the Kindle to show it around indeed was the first part of our mission accomplished.

Content-wise we decided to target beginning and mildly experienced Qt developers, and present the book in some form of cook book, with sections about how to solve specific problems, for example writing file archives, storing configuration, spell-checking, concurrent execution of tasks, or starting to write a new application.



There already is a lot of good content in our API documentation and on techbase.kde.org, so the book is more a remix of existing documentation spiced with a bit of new content to keep the pieces together or to adapt it to the changes between kdelibs 4 and Frameworks 5.

The book lives in a git repository. We will move it to a more official location a bit later. It's a combination of articles written in markdown and compiling code, from which snippets are dragged into the text as examples. A little bit of tooling around pandoc gives us the toolchain and infrastructure to generate the book without much effort. We actually intend to automatically generate current versions with our continuous integration system, whenever something changes.

While some content now is in the book git repository, we intend to maintain the examples and their documentation as close to the Frameworks they describe. So most of the text and code is supposed to live in the same repositories where the code is maintained as well. They are aggregated in the book repository via git submodules.

Comments and contributions are very welcome. If you are maintaining one of the Frameworks or you are otherwise familiar with them, please don't hesitate to let us know, send us patches, or just commit to the git repository.



I had fun writing some example code and tutorials for creating new applications and how to use KPlotting and KConfig. The group was amazing, and after some struggling with tools, network, and settling on what path to take, there was a tremendous amount of energy, which carried us through days and nights of writing and hacking. This is the magic of KDE sprints. There are few places where you can experience this better than in Randa.

Update: Many people are involved with creating the book, and I'm grateful to everybody who is contributing, even if I haven't mentioned you personally. There is one guy I should have mentioned, though, and that is Bruno Friedmann who made the wonderful cover and always is a source of energy and inspiration.

2 comments: