On finishing Season of KDE: improving Kirigami docs

I wrote my first Season of KDE blog-post 3 months ago… and have since forgotten to write any updates. It’s time to address that!

Since January, I’ve been working mainly on improving the documentation for Kirigami. Back then, the Develop wiki had some pages teaching newcomers how to create a Kirigami application, but these were a little disjointed and didn’t really lead readers towards any specific goal.

There were also a lot of aspects and components of Kirigami that weren’t properly documented. Some of the existing materials also needed revising in terms of style, structure, and clarity.

Tutorials

Before Season of KDE I’d recently started tinkering with QML and Kirigami. I wanted to create a simple application that would let you count down the days towards a date, like those you can get on your phone, but without all the obnoxious ads. Since I had no real knowledge of these tools, I started following the tutorials on the KDE Develop wiki, which was a great way of finding out what the problems were with these tutorials.

I went with the idea of the date countdown app and used this as the final goal of the tutorial. If you read through the tutorials now, you’ll find that each page builds towards creating such an app. The new tutorials go over all the essentials that you would need to know to create a basic Kirigami application, covering everything from setting up the development environment, to how to use Kirigami components, to how QML signals work, and so on. Care has also been taken to explain concepts that a beginner developer might not know much about, such as the aforementioned signals. I point this out because I, as a beginner, did not know how signals worked. 😬

These new tutorials should make it quite a bit easier for new developers to come in and learn how a chunk of KDE development works. Hopefully we’ll soon have an influx of enthusiastic new developers bringing new applications to KDE, or helping out with our existing apps! 😀

These new tutorials can be found in the Kirigami section of the KDE Develop site. The project I had initially begun before SoK is now called DayKountdown and is part of the Plasma Mobile namespace!

Beginners

Also helpful to beginners is a new page placed at the end of the new tutorials. This page has been designed to contain everything a newcomer might need or be interested in after creating their first Kirigami application.

Taking a page out of GNOME’s newcomer guide, we have a dedicated section for new contributors. Provided is a summarised list of contribution guidelines, along with active projects that we recommend new developers can contribute to. These projects are organised in terms of complexity and feature useful links where readers can learn more about them. I hope these will encourage readers to become contributors!

There are now also a number of handy links to resources readers can use to learn more about the various tools used in KDE development. We’ve linked to some of the other tutorials available on the Develop wiki, as well as more general resources available elsewhere tackling C++ and Qt. Whereas before readers would have had to search for their own resources, now they will have an index of handpicked websites where they can go and learn more.

This page can be found here.

Component pages

Another big effort has been to expand the number of component pages in the Kirigami documentation. Previously, there have only been a limited number of components explained in the wiki, and as a result, new developers were never made aware of the breadth of components offered by Kirigami. A large part of the work in this Season of KDE project has been to address this problem.

With my last SoK merge request, we will go from having 3 component pages in the wiki to having 12! A range of cool Kirigami components now have their own pages, from inline messages to overlay sheets to form layouts and more. Carl Schwan and I are still working on polishing the merge request and getting it ready, but once it lands, it will really help the documentation take shape. The wiki should become much more useful for those interested in learning more about what they can create with Kirigami.

That’s not to say Kirigami is fully documented yet. It isn’t! But I think it’s a step in the right direction.

My time as a Season of KDE participant

6 months ago, I really didn’t know how to code at all. I’d written a lot about open source in the software in the past — I’ve advocated for it for a long time — but I never really knew how any of it worked.

I still don’t know how most things work, but I can definitely say I have learned a lot about KDE. Working on the Kirigami docs has been a very fun experience, partly because creating apps is fun in and of itself, but also because I can now grasp at how some of the applications on my computer have been made. That feels like a big-brain moment.

I must also thank my mentor Carl Schwan, who has been super helpful throughout these 3 months. Whether it has been combing over my ungainly merge requests, or reviewing the code for DayKountdown, his advice has been great and it has helped me become a (slightly) better coder.

Finally, it’s extremely fulfilling to have contributed to a software project that I have been using for the longest time. Thank you for merging my MRs!!!! I am sure there will be more of them to come, and I am looking forward refactoring lots and lots of my code 😀