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

Kirigami documentation in the KDE Develop site

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!

DayKountdown in its starting view.

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.

Kirigami-based applications for newcomers

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 😀

 

 

SoK 2021: Post 1

Hello fellow KDE people! I’m Clau, one of the new Season of KDE students. I’ve been a Plasma user for a long time: it was actually the first DE I ever used, back in the early KDE3 days, and it has been my desktop of choice ever since. Needless to say, I’m stoked to be able to contribute to such a cool (kool?) project.

I’ve written about FLOSS stuff for a while now, but recently I’ve been working on my coding skills too. I decided to help with documentation efforts as this would help newcomers and also allow me to learn more about how KDE’s best apps are made. I’ll be working under Carl Schwan, who will make sure that the upcoming content in the docs is the best it can be. Documentation is important for any project, and we have identified a few areas which I will be working on improving over the next few months. These include introductory tutorials, Kirigami’s docs, and more. My hope is that these efforts will ensure that the community of KDE developers keeps growing!

Over the course of Season of KDE, I will continue to provide periodic updates on how things are changing at develop.kde.org. Feel free to reach out to me on Matrix if you have any ideas or suggestions! 🙂

 

4 things I learnt as an intern, or how to avoid fetching Tim’s coffee

My last day at Codethink was on Friday, August 30th. It was the last day I hammered away at the keyboard of a Thinkpad, on a table covered in the dozens of yellow Metrolink tram tickets I’d collected over my 3 months in Manchester.

That was a week ago. I swapped 7.30AM alarms and brisk walks to Cornbrook Tram Station for 12PM wake-ups and bleary-eyed trips to the fridge for the glass of milk I call breakfast. Not that I’m complaining — I was never fond of wrestling with my umbrella on the cold, damp walks to the tram — but sitting in bed with nothing to do while the hours tick-tock by has filled me with boredom.

Rather than queue up the umpteenth episode of Supernatural, then, I’ve decided to use one of my few marketable skills and write about my time at Codethink. Here are the things I learnt there.

You might get used to 7.30AM alarms, but you’ll never get used to 5 hours of sleep

Late sleepers take note: it’s possible to get up early. But it’s impossible to make it through an 8-hour work day, 5 times a week, on under 6 hours of pillow-time.

This was my first wake-up call, and yes, that pun was absolutely intentional. Part of the shift from a student life to a -slaving- working life is learning from your parents; that means going to bed early and getting up early, just like mom and dad.

Coffee will become an indispensable ally. That’s assuming you haven’t already developed a caffeine addiction during exam season.

Things are usually the way they are because reasons

By the end of my very first week, I had already developed a laundry list of complaints about the way things were done at my new workplace. My supervisor, Tim Pockney, had to listen to me rant and rave about all of them. Why does the website look like *that?* Why do we not have a Facebook page? Why, in the name of all that is holy, *do we have to use GitLab to upload new blog posts instead of a tool like WordPress?*

That last one still grinds my gears. But now I know the reasons why all of those things are the way they are, and it’s not due to incompetency. It’s usually the case that:

A) there are more pressing issues that take priority, or
B) people have a set of reasons for doing things (or using certain tools) the way they do.

 

Poor Tim was keenly aware of each issue I raised; but one has to weigh the benefit of pulling a programmer off a client’s project for the sake of updating the website, whether the time invested in setting up a Facebook page will lead to acquiring new clients, or, and I say this through gritted teeth, whether the convenience of using WordPress is worth dealing with its many security vulnerabilities.

In the eyes of people far more experienced, far more business-savvy, and in far higher positions in the company, these trade-offs were simply not worth it. That’s not to say that the feedback was not appreciated — in fact, most of them agreed to some extent with the problems I raised, even if they did not agree with the solutions — but it’s important to recognise that things are usually the way they are for a number of very good reasons.

Bring more than just your ass to work

Chances are, unless you work a job straight out of Dirty Jobs, you were employed not just for the sake of filling a role but to also provide value to the company in question.

Pumping out text, code, or numbers is just one of the ways you provide value to your employer, and more often than not it’s not a particularly effective way of doing so. /That’s not to say you should stop doing your job,/ but you are far more valuable as an employee that contributes to and builds upon the way the company conducts its business. This could be as simple as giving your superiors ideas that could increase productivity, efficiency, or income, even if these improvements are marginal.

My ‘big brain’ idea was to post the articles I wrote for Codethink on Reddit, which resulted in the number of average monthly unique visitors to Codethink’s blog growing over twofold in respect to the prior 5 months of 2019. Before patting myself on the back too hard, I must give other factors their due credit; Tim’s expertise with LinkedIn and Twitter was one contributor to those figures, and the inroads he’d made with the company blog in early 2019 certainly helped grow the website’s traffic.

I will say, though, that something as simple as posting articles on Reddit provided a noticeable boost to traffic — and it is thanks to ideas like these that Tim grew to see me as more than just a whiny, snotty, know-it-all intern.

Bigger isn’t always better (or Micro =/= soft 😉)

I’ll preface this by saying that Codethink is not a small company. By the time I had left it employed over 100 people.

But some of the other companies I’d applied to intern for had employee counts in the hundreds of thousands. That’s a lot. One of them had almost as many employees as my hometown, and I’ll let you figure out which company this is by yourself.

Sure, those names would look very impressive on your CV. Trying to be heard at such a company, however, is like trying to make small talk with someone at a Metallica concert. The chances of you making any significant contribution as an intern are very, very small.

When I got plopped into the Sales office at 35 Dale Street, that was because there wasn’t such a thing as a Marketing department — me and Tim were pretty much it. That’s scary as hell, and rewarding as hell, for pretty much the same reason: your work is much more visible. The good thing is if you do it well, the compliments, job opportunities, and recognition start to pile up in your inbox.

At least that’s what I’ve been told. My mom says my work is very good anyway.

One last thing

I’ve cracked a lot of genuinely unfunny jokes over the last couple of paragraphs, and I apologise for wasting your time. But I must also extend my apologies to everyone in Codethink’s Manchester offices, and especially to the Sales office, my fellow interns, and Tim, who had to endure me the most. I’ll miss bothering you very much, and I’ll miss the tea and biscuits in the break room even more.

Oh, and I almost forgot. Thanks for the internship! ❤