A couple of weeks before the KDE Randa Meeting of 2014, the meeting’s organizer Mario Fux suggested to have a book sprint to help developers adopt the newly released KDE 5 Frameworks. In the Open Source spirit, the idea was not to start from scratch, but rather to collect the various bits and pieces of documentation that exist in different places in one location that offers itself more to a developer than before. Valorie Zimmermann stepped up to organize it (many thanks!), and a number of people volunteered to take part. After a week the project completely changed its orientation and struggled and found and also newly defined its place as a part of KDE’s documentation efforts. And it produced an initial version of the book, which is currently circulated on people’s ebook readers around here.
The first question to clarify and find concensus about was that of the audience of the book, and that also made an inherent conflict apparent. The target audience was defined as readers with programming experience in C++ and some Qt. Also, it is supposed to be useful to experienced KDE programmers as an easy way to jump into frameworks and programming mechanisms that they are not familiar with. And the inherent conclict was that the intended contributors to the book are those experienced KDE programmers, ideally the authors of the frameworks, and those do not have an itch to scratch by spending their time writing for newcomers. A rather convincing compromise for everybody is that the book will have fulfill a specific role, and that is to complete the spectrum of development documentation going from very basic questions (of which many today are better answered in the Qt Project forum) to cookbook style feature stories (this is the part that was missing) all the way to the already quite good API documentation.
The second question was that of tools. The flaky network was just the final blow to the expectation that the en vogue authoring tools (Booktype, Flossmanuals & co) would do the trick. They simply do not integrate well with the workflows of developers and a Free Software community in general, which is almost exclusively based on revision control and infrastructure that ties the pieces together. Information like text articles and code snippets are simply never supposed to be copy-pasted form one place to the next, as this would only create hard-to-spot errors and duplicate work. So while it sounded like a compromise to fall back to using a git repository of Markdown files in combination with pulling in the actual frameworks as submodules, it turned out to be the saving grace. There are still open questions, but the general approach is serving us well so far.
The last big question was that of how to integrate the book into the existing infrastructure. We decided to table a lot of these details, to be able to focus on producing content. In the end, the content is in simple to convert and integrate in all kinds of formats. The vision however is to have the production of the book in HTML, PDF and ePub formats integrated into CI, and the current version of the book available all the time. This also includes to decide in what way to revision and “release” the book. An option is to polish and copy-edit a new edition in the same cadence as the KDE software releases. This way, the common spirit of “let’s get it done and out there” could be beneficial to also keep the cookbook up to date. Let’s see.
If you are interested in jumoing in to help or to see what the current state of the book looks like, Valorie has all the details in her post.