SoK/2021/StatusReport/Claudio Cambra

Improving technical documentation

Kirigami is one of KDE's most important frameworks. It is used by KDE developers to produce attractive applications that work across desktop and mobile environments and across many operating systems.

However, the Kirigami developer documentation on the KDE Develop site was scarce in content. This made it difficult for newcomers to fully uncover Kirigami's capabilities. A significant part of my Season of KDE work has been devoted to addressing this, working towards the goal of making the Kirigami documentation detailed, complete, and beginner-friendly. We are now much closer to this goal than we were in January.

Working on this project has also helped me learn a lot about Kirigami too. One of my personal projects, DayKountdown, has gone from being a blank window to being a (relatively!) usable, convergent application. DayKountdown now forms part of the Plasma Mobile namespace on KDE Invent and the aim is for it to eventually become a showcase of Kirigami's capabilities. Right now, it just counts down the days towards a date (with a few neat extra pieces of functionality).

Throughout Season of KDE, I have improved several additional areas of the KDE Developer documentation. I have also assisted other community members in the writing and drafting of new documentation.

Links

Documentation site

DayKountdown

Repository for DayKountdown

Blog posts

Timeline

January 2021

January involved a lot of getting used to Invent. Working on small bits of the documentation was a good way to learn about merge requests, forks, suggestions and so on, as I'd only used git's clone, pull, and push before.

I started by fixing the things that were most obviously broken yet also not a massive undertaking. The old KDE Frameworks tutorials had several issues in them and seemed like an obvious first problem to tackle.

These were some of the smaller MRs I made during SoK, they were bound to be helpful for newcomers who tried their hand at the KF 'Getting Started' section and would end up not being able to compile the examples.

February 2021

February saw MR6, a significant MR which overhauled the tutorial section of the Kirigami documentation. The old tutorials were disjointed and didn't build towards any specific goal. They also missed out on a lot of important information that could be helpful to beginners, such as QML's signal system, important components like Kirigami overlay sheets, and more.

The new tutorials are based on my own experiences trying to create DayKountdown. They go through concepts that new QML programmers might not fully understand, such as the resources system or the aforementioned signal system. They also cover essential Kirigami components and explain the way they work in simple terms. The tutorials also lead the reader all the way through building a simple working version of DayKountdown, which makes the process of completing the tutorial far more fulfilling.

March 2021

March saw some slightly smaller MRs than February, though they were important nonetheless.

Several fixes were added to the new Kirigami tutorials, particularly in terms of clarity for newcomers. A new page was also added after the tutorial section to guide newcomers into projects they could contribute to, or additional resources they could explore to learn more. Again, these changes help make the documentation more accessible for people who might be interested in joining the community.

There were also some fixes added to the KCM page of the KConfig documentation, which was very heavy in code and very light on explanation and clarification. This is now no longer the case.

April 2021

In April, another big MR was opened. This one added nine new Kirigami components pages to the Kirigami documentation, significantly expanding the section from the three pages it had before. This MR tackles one of the largest problems with the documentation, that being that an inexperienced developer is unlikely to find out about, or know how to use, a significant portion of Kirigami's components without digging deep into the API documentation. While 12 pages do not encompass the entirety of the framework, it is nonetheless a solid step towards providing beginner-friendly Kirigami documentation on KDE Develop.

During April, I also helped edit another MR, which added a new Akonadi application development tutorial to the KDE Develop site.

Conclusions

Overall, I would say Kirigami's documentation still has a long way to go. As one of the most significant frameworks of the KDE Community, we need to continue documenting all aspects of the framework. This is an essential aspect of facilitating access to KDE projects and of encouraging newcomers to participate in them.

Kirigami's developer documentation is, however, in a much better shape now than it was back in January. In that sense, I believe the goal of improving the technical documentation has been met, though I hope that work on this are of the docs continues in the future. I will certainly continue to contribute where I can!

My discoveries

Git has more functionality than clone, pull, and push.
QML is a fantastic language for front-end development.
Kirigami helps make life very, very easy.
C++ can be complicated for a noob, but it is not impossible.
Setting up a build system can be frustrating, but makes life easier in the long run.
Developer documentation doesn't have to be verbose, but it cover all the bases of the audience it is aimed at
Documentation is time-consuming work!

Contact

You can reach out to me on Matrix: @clau-cambra:kde.org

Images

A screenshot of the new Kirigami documentation area

A screenshot of the page for aiding newcomers to participate in KDE projects