I made substantial changes in the KDE Developer Platform documentation over the years. I am effectively its docs maintainer and have the largest number of commits in the repository. This is due in large part because I started contributing to it in 2021, applied as a KDE documentation contractor in late 2023, and started officially working with KDE development onboarding docs in 2024. I'm one of multiple furries contributing to KDE. :3
You can skip reading about my Linux history and go straight to my KDE docs job or to the current state of KDE onboarding docs.
A bit of my history🔗
Back in 2015 I was using Windows 8 Home Single Language when I started searching for some art software to learn to draw. Photoshop is actually very unintuitive and the keyboard shortcuts weren't working for me; Paint Tool Sai had better shortcuts, but the UI confused me. It's when I found Krita, which became my favorite software in large part because the basics seemed intuitive and the keyboard shortcuts were so much more comfortable than the alternatives, but also in part because it had a cute mascot drawn by a furry. That's how I heard about KDE for the first time.
Being a Portuguese and German Language and Literature university student who was trying to learn German, in 2016 I was pissed off by Windows making money with licenses that prohibited you from installing other languages. It's effectively knowledge gating for greed reasons, so I went looking for the reasonable alternative, Linux. I started with LXDE and XFCE, of course, since I wanted everything to be lightweight (unlike Windows).
I switched to KDE Plasma 5 in 2017.
A year later, in 2018, I started using Reddit. By then I knew one thing or two about Linux, and started providing user support there. Later on I was dissatisfied with the r/KDE sidebar, so I volunteered to fix it as a moderator; more importantly and selfishly, I wanted custom flairs for myself, so I selflessly fixed all custom flairs on new Reddit (I strongly dislike old Reddit to this day). The current sidebar of the new Reddit version of r/KDE still is 90% of what I did back then.
Whenever I think about that one video from Kurzgesagt about selfish altruism, I think of how I improved r/KDE for others if even tangentially because I wanted a flair and nicer links to docs that I used often. My selfish needs were met by improving things for everyone, that’s how it should be. It's just another way of saying scratch your own itch.
Now being a mod, I started partaking in KDE Promo as well.
In late 2018 I started contributing to the KDE wikis, specifically fixing most of the Get Involved pages. That was around the time I got a job as a translator at an academic papers translation agency / publisher.
Because of this, I started contributing to translations, becoming a trusted KDE translator in late 2019 with an account with merge rights. That would go on until mid 2020.
2019 is when I really started going down the rabbit hole 🐰. I like ergonomics and I was a work overachiever: I produced more than what was needed, and was always seeking ways to optimize my workflow. This partially lead to me being burned out and leaving the company years later.
Hence I made a bunch of keyboard shortcut analyses on my blog at the time. Back then I felt very proud of what I accomplished, if anything, because it lead to a consistent keyboard shortcut scheme in Plasma that uses its virtual desktop strengths instead of trying to imitate GNOME, i3wm or Windows. Meta is associated with moving, Ctrl is associated with switching, and Shift is associated with transferring. Hence, Meta+Ctrl+Shift transfers a window between desktops and Meta+Shift transfers a window between screens; Meta+Ctrl+Shift also switches between desktops as a result of transferring windows between them, Meta+Ctrl switches between desktops without transferring; lastly, Meta moves the window around by snapping it (and additional snapping moves it to another screen). It’s all very smart.
I might now regret those blog posts because of how badly they were written and how overwhelming it is to read them, but I’m definitely proud of the intuitive shortcut scheme I devised.
It was around that same time when I made the "Contributing to KDE is easier than you think" series of blog posts.
Moving on, 2020 was pretty active. I started contributing to KDE web, while still being a Reddit mod and translating occasionally, and playing a bit with desktop publishing and Scribus. That was around the time Phabricator was being deprecated in favor of Gitlab (I think).
I got a large interest in debugging and triaging, though my triaging was very fleeting and didn’t last long. Debugging in particular was reflected in me fixing the wikis as well.
Soon after I’d start learning development while having no formal IT knowledge prior to this. I had tried my hands with multiple programming languages so far, but none actually sticked; the closest was Perl (and Raku is also pretty cool). I'd eventually find out that I actually really liked C++. The parts of C++ I liked the least were actually old C++, as it's closest to C. I quite liked this talk by Kate Gregory about having developers stop teaching C++ like it's C, and I enjoy keeping up to date with the latest C++ 20/23/26 like Concepts, ranges and monadic functions.
Actively focusing on learning development is why in early 2021 I’d start with my first major code contribution: the “Default Applications” section in System Settings. Coming from XFCE, I wanted a good looking default applications page. I made it work, actually! But the requested changes were too much for me even 2 years later, so Méven took over what I did and got it to the finish line in late 2022.
My attempts at development also reflected in learning how to compile raw, with Kate, KDevelop and QtCreator, in attempting to contribute to Subtitle Composer, and in adding many KRunner web shortcuts because Gitlab search just plain sucked.
(On the matter of subtitling, did you know I subtitled Veritasium's What Everyone Gets Wrong about Gravity to Brazilian Portuguese using Subtitle Composer? If you download the subtitles you'll see my credits at the end.)
By then I had a good understanding of KDE infrastructure in all areas, pretty much.
2022 is when I started touching docs.
To summarize my history:
- user support
- promo
- wikis
- translations
- websites
- triaging
- development
My KDE docs history🔗
I was originally not a fan of QtQuick and QML. It didn’t help that our Kirigami tutorial was in a terrible shape back then. I knew some C++, so I started with small QtWidgets / KXmlGui.
The most complicated part about our tutorials was actually the poorly explained CMake.
CMake is important because without it you can’t build. So it doesn’t really matter how well written the development part is unless it builds.
Rule number one of documentation:
Never break the docs.
If the user can’t get a functional project by the end of a tutorial, the tutorial failed. So that should be priority number one. I did an entire Akademy talk talking about how docs is part of the product, and broken docs effectively means a broken product.
Now, I actually quite like CMake. I’m just dissatisfied with the state of CMake docs.
To this day I think there is only 5 good resources on CMake, to be checked in this specific order:
Anyway, I first touched KXmlGui by making it fully functional and have screenshots, in addition to mentioning actual build instructions. My fix was so effective, in fact, that there were very few changes to this day.
KXmlGui is our framework for making application windows using only C++. It extends QtWidgets with lots of convenience and standard features, like default Settings and Help menus that show app credits.
I started fixing our flatpak documentation next. In particular I was displeased with the requirement of knowing JSON syntax to be able to even make the thing build (as I myself struggled to understand JSON syntax), so I added some general explanation on how to write a JSON flatpak manifest.
I started a CMake tutorial that went unfinished after a year, and was closed. I still want to make a proper CMake tutorial leveraging our extra-cmake-modules.
extra-cmake-modules (ECM), is a collection of convenience features for CMake, like default compiler settings or the ability to uninstall. Any application using CMake can use it, not just KDE applications!
In 2023 I started touching the Kirigami docs. I finally did the plunge into QML, and the Kirigami tutorial was in a very bad shape. Like real bad. The code samples were incomplete, almost no links, too technical explanation, the order of pages was wrong, when things would build they wouldn’t run, no docs to figure out how to troubleshoot.
I figured it was a priority to fix most links and to at least make things buildable. I made the mistake of doing everything in one go, rendering a merge request with 185 threads and 131 changes.
I then went on to do housekeeping in Develop with smaller fixes. Such a large MR burned me out a bit. In the meantime I started porting KTimeTracker to Qt6, which was a major breakthrough for my development learning, though I would only publish it later on.
With the lessons learned from the KXmlGui and Kirigami tutorials, I made formatting and style guides for Develop. Note the final section about learning about standard documentation practices!
Making established practices known to others is a best practice in the documentation world, and I had been reading about improving documentation since early 2022, so by then I had a good idea of how it works.
I then went on to write docs for Kirigami Addons after I tried my hand at it for a while. It’s a cool QML library for Kirigami settings pages, I felt like new contributors should know about it for their new apps.
Then another majorly significant merge request: Plasma Style. It is one of the docs projects I felt most proud of, and it was recently mentioned in a video from a designer called Juxtopposed.
It was extremely painful and miserable to fix. I had to reverse engineer the inside of SVG files from both Breeze and Oxygen in order to make it a reality. After this I made it look nicer and more readable.
In effect that tutorial is not really a tutorial, but rather a reference guide. The actual tutorial is a video series by Niccolo Veggero, without its foundations I would not have been able to make the guide.
While continuing the housekeeping of Develop, I started looking into other platforms, like Windows. This rendered an interest in Craft and in application styling, or rather, having Kirigami apps actually look correct everywhere. This was a longstanding issue in our Kirigami docs: how inconsistent the resulting project would be when built normally on Linux, as a flatpak, as when built on Windows.
I ended up learning Craft, qqc2-desktop-style and the new KIconThemes effort driven by Christoph Cullmann to make KDE apps look correct in other platforms.
Naturally, this was the next goal to be tackled in our Kirigami docs. The Kirigami tutorial now worked on Linux; it now had to look right and work on Windows, too.
I also got interested in how our infrastructure works, and through playing with my own selfhosted test Gitlab instance, I managed to update our CI wiki page.
My new job working for KDE🔗
By the end of 2023, I saw a job offer as a documentation contractor for KDE, and I took it. I was already a fairly established contributor and I was already working on docs, so I got the job despite having no formal training in technical writing or IT.
Now, I must say two things about this:
- I knew beforehand that applying and not getting the job is still better than not applying and then regretting it
- I knew beforehand that more often than not the most desirable job offers get less applicants than they should because people think they're not suitable to apply
This might sound obvious when put into text, but it isn’t. Most people need to be slapped in the face with this for it to actually sink in. Leader training and coaching might be misuse of social psychology to make cash cows using garbage language, but this one thing they get right.
Anyway: if you are passionate about open source and want to put in the effort to improve it, you should check your favorite projects’ websites and see if they have any openings. Then apply. You might get it. I sure hope actual passionate humans will be the ones applying to these sorts of jobs before any LLM sloperators / DevSlops apply to them...
Moving along, now in 2024 I was effectively a contractor. I immediately started searching for technical writing resources to learn more.
Turns out that the vast majority of good technical writing content only exists in books. The rest is just online talks. Unfortunately, of these, too many are enterprise focused, and are thus difficult to apply in open source environments. This means I had to do some filtering.
However, one source stood out as the gateway into this topic: Write The Docs. Go check it out together with the Google Technical Writing courses, it's really good.
While learning on the side, I was also thinking of how to go about KDE docs from then on. I already had plans for Kirigami and the Get Involved pages, but I needed to devise priorities. I also needed more development experience for me to document development practices.
I spent a large amount of time working on KTimeTracker to get development experience and doing work on the KXmlGui API (since at the time the QML docs generation was rather broken). Then I went on to fix our wiki page for getting involved with development.
I had some priorities in mind:
- Porting tutorials to Qt6
- Development wiki
- Moving Development wiki contents to Develop
- Prepare to switch to kde-builder
- Better multilanguage support (Python, Rust)
- Plasma tutorial
- Appium tests
- Building software without kdesrc-build / kde-builder
Porting the tutorials to Qt6 was straightforward, although I had to make tutorial adaptations for this.
The development wiki page required some updates and was straightforward to port to Develop. I also made buttons to make it more presentable, but MediaWiki is really not suitable for this.
An Appium tests tutorial was added soon after testing every aspect of the development wiki page, since it was directly related to it. This was actually painful because I had to rely on my weak Python knowledge to understand how other KDE people were doing GUI tests, and it was very difficult to find the correct docs for upstream Appium and Selenium as it’s spread out in multiple places. Like seriously, the upstream docs were both so barebones and so spread out that even our current tutorial linking is all over the place.
In the meantime I’d be learning Python and Rust on the side.
With the money acquired by working for KDE, I managed to purchase a Steam Deck in March 2024. As you probably know, it came with a Plasma 5 X11 session for the desktop. I tried using it as my main computer for quite a while (forcing the Wayland session), and this resulted in two things: the Building KDE software manually and the Building KDE software with distrobox and podman pages. I’m already a podman fan and had been using it before getting my Deck, and with my prior CMake experience all I needed to do was put my knowledge on paper.
I’m proud to say my current CMake docs are effectively one of the best out there (even if it’s just about the cmake tool), and that many of our new contributors have been using distrobox on their immutable systems ever since (but especially in 2025).
In the middle of the year it became clear that we would switch from kdesrc-build to kde-builder as the de-facto tool to develop KDE software, so I put a migration plan in place that would stick around for half a year. It’s important to have a migration plan of some level in our current docs, otherwise we get confused users who effectively lose support docs with no warning. It was nevertheless quite the major effort.
Now the Plasma tutorial... well. That was a jigsaw that required too many pieces for me to assemble. As mentioned before, QML doc generation was broken back then, so the only reasonable source for learning our QML API was the source code docs. But that required knowing Kirigami extensively and... well, our Libplasma QML API was actually lacking even source code docs, so in practice what one needs to do is read the actual source code to figure things out. There was also a lot of historical baggage to go through.
I think you might have noticed by now, but the way documentarians do docs is by first learning the subject and then teaching it. This means becoming enough of an expert on a topic before writing about it. You should never write new docs not based on your knowledge or experience (this also means no LLMs by the way).
Anwyay, Plasma was too large a thing for me to address this soon.
That plus the fact that Plasma itself got an update in Qt6 to use less Libplasma specific stuff and more Kirigami stuff meant I had to focus on Kirigami instead anyway. Additionally, there was now a potential fix for our broken QML doc generation on sight: Qt’s internal QDoc tooling.
The rest of 2024 mostly consisted of doing the required kdesrc-build / kde-builder changes, polishing it together with the Kirigami and Python tutorials. By the end of the year I also helped port quite a bunch of APIs to QDoc, though I definitely wasn’t the star of the show, Nicolas Fella was.
I struggled because I had to learn an entirely new thing, QDoc, as well as address its jank. Every documentation tool has its jank mind you, you just have to deal with the existing problems, and the end result with QDoc was still much better than our previous Doxygen system.
It was cool to finally work with actually well generated QML docs. I was supposed to work on that since the beginning, but it was sure painful by the time I started.
This year, 2025, I managed to work on that and on supporting kde-builder, Craft, Python with Kirigami, adding a new Rust with Kirigami section, test all aspects of kde-builder, test it on all major distros, testing Kirigami on Android, started porting QML things to the new declarative registration, and added many new sections to assist with our existing kde-builder stuff.
And this while having to deal with IRL family health emergencies from the second half of 2024 onwards.
The current state of KDE onboarding docs🔗
All that just to say that I’m finally content with the state of beginner onboarding docs in our KDE Developer Platform. That is to say, all the beginner docs fixes I wanted to add to Develop are either already there or have merge requests ready or almost ready.
Here’s the following improvements I did in Develop since I started contributing there:
Kirigami tutorial
- Builds and runs
- Has examples that match the screenshots
- Full source code at the end of relevant pages
- All links are functional
- Is ported to Qt6
- Is ported to declarative registration (MR)
- You can start the Kirigami tutorial with C++, Python or Rust now
- You can prepare the project to build on Windows
- You can prepare the project to build on Android (MR)
- Is tested on Linux, Windows, building manually or with distrobox
KXmlGui
- Builds and runs
- Has examples that match the screenshots
- Full source code at the end of relevant pages
- All links are functional
- Is ported to Qt6
Building KDE software
- Fully functional
- All links are functional
- kde-builder mentions custom Qt installs now for older distros
- kde-builder has a troubleshooting page
- kde-builder has a common developer tips and tricks page
- Craft on Windows page
- Building manually with CMake page
- Building with distrobox page for people on immutable distros
- There’s a table explaining distro compatibility
- You can now learn how to figure out the most common problems yourself
- There’s a full blown page for Qt/KDE learning resources curated by moi
- You can now learn how to crossreference KDE source code
Python tutorial
- Builds and runs
- Has examples that match the screenshots
- Full source code at the end of relevant pages
- You can now understand how Python packaging works
- You can use Flatpak for packaging
- It mentions KDE Frameworks Python bindings
Rust tutorial
- Builds and runs
- Has examples that match the screenshots
- Full source code at the end of relevant pages
- You can use Flatpak for packaging
- It mentions KDE Frameworks Rust bindings (MR)
Contribution guidelines
- You can now learn how to use Hugo-specific formatting in Develop
- You can now learn how to style your docs in Develop
- The style guide links to well-known technical writing resources for beginners
In other words, we have accomplished the following goals:
- The beginner docs are not broken
- Kirigami should be the entrypoint for new apps
- The flagship tool kde-builder is extensively documented and tested
- Users in immutable distributions are not left in the cold
- We can appeal to Python devs now
- We can appeal to Rust devs now
It took a long time to arrive here, in large part because our building tutorials required a lot of care, and Kirigami has 33+ pages to maintain. This is a lot of pages for one person to maintain actively!
Now the beginner onboarding docs can (hopefully) just get iterative fixes, unless at some point we make larger changes.
That is, ignoring the elephant in the room: Plasma.
Now with QDoc and me fixing the documentation in Libplasma, it should be much easier to actually fix our Plasma widgets tutorial, so it could be a goal for next year. In the meanwhile I see Zren started working on it.
Speaking of next year, I can now actually focus on the non-beginner onboarding docs! In particular I feel like adding content related to branding for companies and distros should align with KDE’s current goals now that Plasma is a strong contender for use in enterprise. That, and fixing the one other section I’ve postponed fixing for too long: the Features section, which showcases our KDE Frameworks libraries.
Now that beginners are well served, we can focus on intermediate content and making our products appealing. This means our flagship product Plasma and our flagship libraries.
Naturally that would go side by side with fixing our API docs. But it sure is looking like a great future: KDE onboarding docs is good now, and it will be awesome next.
dragotin
With the start of the new year, I am very happy to announce the release of version Kraft 2.0.0.
#this-week-kde-apps:kde.org
