KDE Frameworks Book Sprint at the Randa Meeting 2014

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.

Hack sprint fuel, the Swiss way
Hack sprint fuel, the Swiss way

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.

8 responses to “KDE Frameworks Book Sprint at the Randa Meeting 2014

  1. Pingback: Links 13/8/2014: Red Hat Enterprise Linux 6.6 Beta, Tizen in Watches | Techrights

  2. Diane Trout

    I’m really interested in this documentation and really would like to read it.

    While reading your post I wonder if a couple of tools from the python community that might be helpful?

    sphinx-doc.org drives most of the python docs, I believe it can work with C++. (Examples http://sphinx-doc.org/examples.html including docs for QGis.)

    The slightly sillier idea is IPython notebook. though its intended for scientific computing it can and has been used to produce book length works. https://github.com/ipython/ipython/wiki/A-gallery-of-interesting-IPython-Notebooks

    • Thanks, Diane! We will get you a copy to read at the end of the book sprint. We are actually jealous of Python doctools :-), but we are dealing with a compiled language, so a few extra steps are involved. Our example programs are,in fact, stand-alone programs that are compiled and tested in CI. To make sure example snippets and the compiled apps do not diverge, we are creating some glue tools.

  3. Allan Holman

    Have you seen gitbook (https://github.com/GitbookIO/gitbook)?

    • Not yet, but thanks for the hint, we will have a look at it. In terms of tooling, so far we haven’t invented much of our own. Most of the effort went into setting up convenient work flows for contributors of code and content, based on our existing Git infrastructure, Markdown and pandoc (for now).

  4. Pingback: How else to help out | Bartle Doo Articles

  5. Pingback: How to contribute to the KDE Frameworks Cookbook | Creative Destruction & Me

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s