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 it will feel familiar if you have ever contributed to Wikipedia or any other wiki.
To contribute to it, you should read the Quick Start 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.
Warning
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 another contributor will make the necessary changes after your contribution is accepted and merged.
It is most often done in collaboration with the KDE Web team.
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.
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
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 KApiDox, which uses Doxygen and Doxyqml.
To contribute to API documentation, you should read the KApiDox readme. You will also need some programming knowledge to figure out what the code does, as well as take a look at Doxygen's special commands and the Frameworks Documentation Policy to have an idea of what can be used for documenting API.
It is important that you do NOT change the API itself unless you know it is harmless (like changing the name of a function parameter).
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.
Mentor program
Getting started with a big project can be hard. Here are some people that are willing to help you one-on-one:
- Burkhard Lück (lueck at hube-lueck dot de) : documentation
- Yuri Chornoivan (yurchor at ukr dot net) : documentation
- Thiago Sueto (thiago dot sueto at kde dot org) : wikis, tutorials and API docs
- volunteer to mentor! Add your name here