Google Season of Docs proposals for KDE

About your organization

KDE is one of the biggest and oldest open source organizations in the world with hundreds of active contributors. We are an international team co-operating on the development and distribution of Free, Open Source Software for desktop and portable computing. Our community has developed a wide variety of applications for communication, work, education, and entertainment.

For Google Season of Docs 2021, KDE is applying with projects in two areas: Kirigami and Uyuni.

Kirigami

Kirigami is one of the tools developed by the KDE community with the goal of making it easy to develop convergent applications between desktop (Linux, Windows, macOS) and mobile (Android, Plasma Mobile). Kirigami development started in 2012 and an increasing amount of new applications are using it, with the first Linux phone shipping with applications built using Kirigami.

Uyuni Project

Additionally for this Google Season of Docs, KDE is also serving as a legal entity for the Uyuni Project.

Uyuni is an open source systems management tool, providing a flexible WebUI and API to manage Linux-based client systems on physical or virtual hardware, including IoT and Edge devices. You can use Uyuni to keep your systems patched and up-to-date, manage containers and virtual systems, understand at a glance what tasks are outstanding, automate deploying new systems, and manage your maintenance schedule. For more information about Uyuni, see https://www.uyuni-project.org/. Uyuni is the upstream project for SUSE Manager, for more information about SUSE Manager, see https://www.suse.com/products/suse-manager/

All documentation for Uyuni is available at https://www.uyuni-project.org/uyuni-docs/uyuni/index.html. The source for both Uyuni and SUSE Manager documentation is publicly available on GitHub, at https://github.com/uyuni-project/uyuni-docs. The documentation is written in Asciidoc, and the toolchain uses Antora to produce the published static site. It uses lunr.js to provide site search, and a custom CSS to provide the colors and layout on the site.

NB: just to clear any possible misunderstandings: SUSE pays a small but dedicated team to write the SUSE Manager documentation and to do some Uyuni-specific contributions. The purpose of this GSoD is to expand on the Uyuni-specific content, with external technical writers. Money will NOT be used to pay SUSE Manager technical writers to do their job.

About your project (Kirigami Cookbook)

Your project's problem

Kirigami is a very nice framework to work with once you know how it works and learned all the small tricks to be productive when building an application. The problem is that until recently the only documentation for Kirigami was the API documentation and while it provides a lot of information about the different Kirigami components, it lacks information on how to use Kirigami efficiently.

Recently a Season of KDE student (Season of KDE is KDE's own outreach program) added an introductory tutorial that explains how to create a very simple application with Kirigami. This already helps a lot with getting started with Kirigami, but since this is an introductory guide it doesn't cover a lot of common problems encountered when developing a Kirigami application and how to solve them.

This makes it harder for newcomers to develop Kirigami applications, as they aren't familiar with the codebase of many existing Kirigami applications, which hurts Kirigami adoption as a whole.

Your project's scope

We recently added a short introduction to the Kirigami documentation, that covers creating a simple application with a few Kirigami components. So now that the bases are covered in our documentation, the goal of this project will be to focus on helping the users figure out more advanced topics in Kirigami. This will use the form of a cookbook showing some examples of how to solve specific categories of problems. This shouldn't explain all the details about the Kirigami API but show solutions for common problems when building an application. For example, the cookbook should be able to answer the following questions:

Forms:' How to create simple forms with checkboxes, text/password fields using Kirigami.FormLayout? How to align multiple Kirigami.FormLayout together? How to display error messages? How to enable keyboard navigation into a form? ...

Routing: PageRow navigation basics and how to use Kirigami Router components for managing the different pages in Kirigami applications.

Convergence: Things to consider and best practices to make the application work both on desktop and mobile.

Theming: How to use the Theme API and make sure the application looks at home with multiple styles and color schemes.

Drawers: How and when to add customized Drawers in an application? How to make the custom drawers work in right-to-left (RTL) environments? ...

Android: How to deploy a Kirigami application to Android?

Work that is out-of-scope for this project:

Improving the API documentation or the introduction tutorial

This project will be mentored by Carl Schwan, the current maintainer of KDE developer documentation infrastructure and an application developer with a lot of experience in using Kirigami.

Measuring your project’s success

We will know if we are successful if we see an increase in applications developed using Kirigami and an increase of new contributors to existing Kirigami applications.

We will track these two metrics (new applications and new contributors to existing applications) in bi-monthly schedules after the documentation is published. Another metric is the number of new contributors to Kirigami itself.

We would consider the project successful if, after the publication of the new documentation:

The number of active contributors increased by 10% a few months after the documentation is published

A few completely new applications using Kirigami are created

Project budget

We expect the participant to write around 20\~40 "how-to" entries for the Kirigami cookbook. An entry consists of a small explanation that it is trying to solve a code example, a screenshot of the result, and a detailed explanation of the code example. The code examples will be provided by the mentor and the length of the explanation will depend a lot on the type of problem, but we expect on average a bit more than a page for each "how-to" entry (not counting the provided code examples and the screenshots). This would result in 3 hours on average for each "how-to" entry. Depending on the fund allocated, we have two budget plans:

Assuming US$40/hour, and that the participant works 10 hours/week for the 2 months of the program:

(10 hours x 8 weeks) x US$40 = US$3,200.00

This would result in \~25 "how-to" entries

Assuming US$40/hour, and that the participant works 15 hours/week for the 2 months of the program:

(15 hours x 8 weeks) x US$40 = US$4,800.00

This would result in 40 "how-to" entries

Additionally, the volunteer stipends are US$500, for creating the code examples. So the final budget is either US$3,700.00 for 25 entries or US$5,300.00 for 40 entries.

Additional information (Kirigami)

The mentor for this project, Carl Schwan already worked with technical writers during the current Season of KDE program (an outreach program hosted by the KDE community) and has experience contributing to the KDE and Kirigami documentation. Together with the technical writer, they analyzed what was missing in the current documentation and this helped create this proposal. Carl also successfully mentored a GSoC project last year and a few Season of KDE projects around KDE web infrastructure. During the GSoC program, they were able to do a massive port of the KDE.org website to the Hugo framework and this reached the front page of HackerNews.

About your project (Uyuni - QA review of documentation):

Review as many guides as possible, testing all the steps, and enhancing the documentation where it's lacking.

Your project’s problem

The Uyuni documentation suite is large, the project is relatively fast moving, and the Uyuni documentation team is small. While the team does their very best to keep on top of new features, bugs, and general improvements, there are always things that fall between the cracks, especially when it comes to differences between Uyuni and SUSE Manager. Add to this the problem of the Curse of Knowledge, and our documentation can always use fresh eyes to improve readability, ensure technical accuracy, and even just fix typos.

Your project’s scope

Participants in this project pick one (or two, or three ...) guides to review. They will then go through them page-by-page, assessing them against the SUSE and Uyuni style guides, and (where possible) testing the steps in each procedure. They should verify that screenshots are up to date, the steps are present, correct, and in the right order, and that no gremlins have snuck in. They will have access to the authors of the content, as well as to Uyuni subject matter experts to help them complete this task. As issues are found, the participant can update the documentation directly by pull requests to the documentation codebase, and changes will be made available at the next Uyuni release.

Measuring your project’s success

This project is successful if it improves any of the books in the documentation suite. We expect contributors to have opened and merged at least 10 pull requests against the documentation during the period of the project. They should have interacted on at least a weekly basis with the documentation team, and have contacted at least one other Uyuni subject matter expert during the project, which resulted in tangible improvements.

Project budget

Time allocation can vary. We assume three to four pages per day of work (includes all research, writing, and editing). Participants should select the book they want to work on, and commit to doing the entire book. Reviews will be conducted as pull requests come in, but the team is always available for advice and support. We recommend starting on a smaller guide to get the idea before committing to a longer one. Estimates are given only for smaller guides, as cadence should improve with later tasks, and will be highly dependent on the participant.

Uyuni QuickStart Guide - 20 pages (5 days, 40 hours)

Upgrade Guide - 21 pages (5 days, 40 hours)

Installation Guide - 41 pages (10 days, 80 hours)

Retail Guide - 54 pages (14 days, 112 hours)

Salt Guide - 81 pages (25 days, 200 hours)

Administration Guide - 137 pages Reference Guide - 161 pages

Client Configuration Guide - 197 pages

Assuming US$40/hour, and that the participant works 10 hours/week for the 2 months of the program:

(10 hours x 8 weeks) x US$40 = US$3,200.00

Assuming US$40/hour, and that the participant works 20 hours/week for the 2 months of the program:

(20 hours x 8 weeks) x US$40 = US$6,400.00

About your project (Uyuni Cookbook) =

Write additional recipes (descriptions of workflows that can be conducted with Uyuni, including step-by-step instructions) for the newly published Uyuni Cookbook.

Your project’s problem

The existing Uyuni documentation contains comprehensive detailed procedures, grouped roughly by the component being acted upon (actions that you do on the server in the Admin Guide, and actions on the clients in the Client Cfg Guide, for example). However, for many common tasks that readers might need to complete, they need to complete many procedures across several different components. Working out which procedures to use, which components to work on, and the order to do them in, can be daunting.

This guide hopes to document the workflows that readers might want to complete, not by providing comprehensive procedures (as they already exist), but to give the high-level steps with links to the appropriate procedures in the documentation suite. In technical communication terms, this publication will document the procedures, rather than the processes.

Your project’s scope

The Cookbook is a new document in progress, intended to be released in mid-2021. This document covers common workflows (or 'recipes') when using Uyuni in real life. The participant would be enhancing the document by writing additional recipes to include.

Examples of recipes are listed here, but the specific recipes will be determined in conjunction with the participant, and can be based on the participant's interests and experience. Reviews would be ongoing throughout the period, with a detailed project plan expected before work begins, and should include time for technical review. Participants will have access to the documentation team as required, and to Uyuni subject matter experts for technical assistance.

Provision a client
Apply and enforce a configuration
Manage a patch cycle
Perform a service pack migration
Perform a security audit
Boot an unprovisioned system and install an operating system
Measuring your project’s success

This project is successful if it adds one or more recipes to the Cookbook. We expect contributors to have opened and merged at least 3 pull requests against the documentation for each recipe documented during the period of the project. The pull requests should cover at least one initial draft, one line edit review, and one technical review of the content. They should have interacted on at least a weekly basis with the documentation team, and have contacted at least one other Uyuni subject matter expert during the project, which resulted in tangible improvements.

Project budget

Assuming US$40/hour, and that the participant works 10 hours/week for the 2 months of the program:

(10 hours x 8 weeks) x US$40 = US$3,200.00

Assuming US$40/hour, and that the participant works 20 hours/week for the 2 months of the program:(20 hours x 8 weeks) x US$40 = US$6,400.00

About your project (Uyuni Short Videos)

Record short 3-5 minute videos for common Uyuni use cases, and create associated documentation of the same procedures for use in the Uyuni documentation suite.

Your project’s problem

Uyuni is a relatively complex system to use, and many of our readers find it difficult to get started with understanding how Uyuni works. At the moment, we have a lot of written content, but very little in the way of multimedia content. Some small, easily digested, and entertaining videos would help to explain the Uyuni value proposition, as well as assist to drive traffic to the project.

Your project’s scope

This project would create a suite of short, user-friendly videos (and associated short how-to guides) for some of the most common Uyuni concepts, to be published on the Uyuni website. Examples are listed here, but the specific topics will be determined in conjunction with the participant, and can be based on the participant's interests and experience. Reviews would be ongoing throughout the period, with a detailed project plan expected before work begins, and should include time for technical review. Participants will have access to the documentation team as required, and to Uyuni subject matter experts for technical assistance.

General overview of Uyuni, architecture, etc
Uyuni Server installation
Uyuni Proxy installation
Adding a product and mirroring it
Onboarding clients form the WebUI
Install, patch, etc clients individually
System groups and System Set Manager. Mass operations from the UI.
SCAP security analysis
CVE audit
Image building
Virtualization: set up a virtualization host, create VM, enroll the operating system in the VM
Monitoring: deploy Prometheus exporters to clients, configure them with formulas with forms, set up a Prometheus server and a Grafana server and connect all together
Advanced monitoring: deploy several Prometheus servers (e. g. for different sites), set up Prometheus Federation, create a Grafana dashboard with the aggregated information
Advanced monitoring 2: set up Alertmanager, send alerts (e. g. using the SNMP exporter)
Configuration management with Salt: write some Salt states for something useful, create and add state channel, assign to system and/or group.
Measuring your project’s success

This project is successful if one or more videos are produced and published. We expect contributors to have opened and merged at least 2 pull requests against the documentation for each video (for a draft and final how to accompanying document), and at least one pull request against the Uyuni site (to publish the video) during the period of the project. Participants should have interacted on at least a weekly basis with the documentation team, and have contacted at least one other Uyuni subject matter expert during the project, which resulted in tangible improvements.

Project budget

Assuming US$40/hour, and that the participant works 10 hours/week for the 2 months of the program:

(10 hours x 8 weeks) x US$40 = US$3,200.00

Assuming US$40/hour, and that the participant works 20 hours/week for the 2 months of the program:

(20 hours x 8 weeks) x US$40 = US$6,400.00

Additional information (Uyuni)

Previous experience with technical writers or documentation

The Uyuni documentation is developed and managed by three professional technical writers. They have a wealth of experience to share with you to improve your technical writing skills. They're also hoping they can learn from you. The team is especially keen to know how to make the process of contributing to the documentation easier, and to understand what could be done to improve the documentation itself, as well as the toolchain and the processes around the documentation.

Previous participation in Season of Docs, Google Summer of Code or others

Uyuni has participated in Google Summer of Code twice, and in 2020 the mentee was dedicated to improving the Uyuni documentation site. This will be our first year in the Google Season of Docs project, however one of the documentation team members was a season of docs participant (for a different project) in 2020.

Total Budget

We have 4 project ideas, each project is independent and contains its own budget. The number of projects we will run this year will depends on how much funding we get and how many hours each technical writer can spend on their project.