Get Involved/documentation

Writing documentation is a great way to start improving your application and KDE software. Your words will be translated to all languages covered by the KDE translations teams, and you will be helping millions of KDE software users to better understand their desktop and applications. Anyone with reasonable English skills and good knowledge of an application can help.

There are four major types of documentation you can work on.

• Wikis
• Tutorials
• Application Manuals
• API Documentation

Wikis

The official KDE wikis use Mediawiki internally, like Wikipedia, so they will feel familiar if you have ever contributed to Wikipedia or many other wikis.

To contribute to the KDE wikis, you should read the Introduction to new contributors page. You may also want to look at the Typographical Guidelines, Tasks and Tools, and the Toolbox pages.

The contribution model works like so: you add the content first, and then someone else may review it (it is not guaranteed). If you want to discuss an addition that was made or will be made, you can use that wiki page's Discussion section, collaborate with the KDE Web team, or make an issue over the Wikis Issue Tracker.

Here are some clearly defined, easy to get started tasks:

• Kill Techbase
• Move user docs from wikis to existing Docbooks
• Move purely promotional material away from Userbase

Tutorials

Our developer tutorials use Markdown and Hugo, and are hosted on develop-kde-org.

To contribute to it, we provide Formatting Guidelines and Style Guidelines.

The contribution model works like so: you create a Merge Request and it gets reviewed before it gets in. This is to ensure the quality of documentation, but if you find it overwhelming, say so, and a contributor will make the necessary changes after your contribution is accepted and merged.

The tutorials section of Develop is mostly maintained by Thiago Sueto and other KDE Developers. The HIG is managed by Nate Graham and the Visual Design Group. The website layout is managed by the KDE Web team.

Here you can find the list of available issues to address:

• https://invent.kde.org/documentation/develop-kde-org/-/issues

Application Manuals

Our application manuals can be checked online on docs.kde.org, and it uses Docbook, which uses XML and can be converted to several other file formats easily.

To contribute to application manuals, you should read the Getting Started with Documentation page, which links to our Documentation Primer.

In order to document KDE projects, you will want to run a recent development version of KDE software. To document third-party projects, you will also need a recent version of that program. There is a special KDE DocBook XML toolchain used to create documentation.

Note

Checking and Viewing the Documents: in order visualize the result of DocBook files in a browser, look at this how-to.

The contribution model works like so: to add new content, you send an email to the kde-doc-english mailing list with the draft that will become the application manual, then you will get feedback on your work and other contributors will help you get the new content in. When the Docbook is finished, either by you or by someone else, it gets added to the project's repository on Invent.

Note

You do not necessarily need to write in Docbook in order to get your contribution accepted. You may write it in a format you are comfortable with, and request another contributor to convert it to Docbook for you.

Alternatively, if you are already familiar with Docbook, you may contribute directly to an existing Docbook file in the project's repository by creating a Merge Request. It then gets reviewed before it gets in.

It is managed entirely by the Documentation Team.

API Documentation

Our API Documentation is generated with QDoc.

Previously we used KApiDox, which uses Doxygen and Doxyqml. Some projects still use KApiDox.

If you'd like to assist with porting the old API documentation to QDoc, see the Port API documentation to qdoc metatask.

The global settings for how the QDoc documentation is generated is stored in the kde-qdoc-common repository.

You will need some programming knowledge to figure out what the code does, as well as take a look at the QDoc Documentation Policy draft and the previous Frameworks Documentation Policy to have an idea of what can be used for documenting API and how to proceed in most circumstances.

It is important that you do NOT change the API itself. If a change to API is necessary, that change should go to a different merge request, and you should wait for it to be merged to proceed.

The contribution model works like so: you create a Merge Request and it gets reviewed before it gets in.

It is managed by the documentation and development teams.

Communicating with the team

There are many ways to get in touch with the team:

You can chat with the Documentation Team in the #kde-docs channel on Matrix or Libera Chat, and written discussion is held over the kde-doc-english mailing list.

You can chat with the KDE Web Team in the #kde-www channel on Matrix or Libera Chat, and written discussion is held over the kde-www mailing list.

Learn more about Matrix, Libera Chat and Mailing Lists.

The KDE DocBook format

We use the DocBook XML standardized format, which allows for ease of translation using our custom tools. The markup is extremely self-descriptive, and many people find it easier than HTML to learn. However, if you are not familiar with it, please read up about it below. To produce quality documentation, please have a look at these guides:

• DocBook Crash Course
• The screenshots specification
• Getting started guide on the internationalization site
• The documentation Primer
• Questions You Should Answer When You Document KDE
• The goals of the KDE Editorial Team
• The KDE DocBook XML toolchain

Tasks

Now that you have a recent version of KDE running, you can get your first contribution committed today! Here are some tasks for beginners:

• Open Documentation Tasks - a list of the few documentation priorities
• Bugzilla listing of screenshots that need to be fixed
• Bugzilla listing of documentation that needs to be updated
• Bugzilla listing of applications missing documentation
• Techbase Documentation page
• Documentation Status
• Mail in your creations to the KDE documentation team.

Mentorship program

KDE is a big community, and translating its software is a big project. It is easy to feel lost when you first start. Several people have volunteered to help new members by answering your questions and pointing you to the right places. You can find a list on the mentoring page.