SoK/2021/StatusReport/Claudio Cambra: Difference between revisions

Revision as of 20:20, 15 April 2021

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

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

MR11: 9 new Kirigami components pages added

@@ Line 43: / Line 43: @@
 * [https://invent.kde.org/documentation/develop-kde-org/-/merge_requests/85 MR9: Fixes and touchups to KConfig KCM page]
 * [https://invent.kde.org/documentation/develop-kde-org/-/merge_requests/87 MR10: Created new page with information for beginners to Kirigami]
+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 ====
 * [https://invent.kde.org/documentation/develop-kde-org/-/merge_requests/94 MR11: 9 new Kirigami components pages added]