Get Involved/documentation: Difference between revisions

From KDE Community Wiki
m (→‎Mentor program: Fix my mentoring email)
(→‎Communicating with the team: Link to IRC channels using irc:// URIs)
Line 63: Line 63:
There are many ways to get in touch with the team:
There are many ways to get in touch with the team:


You can chat with the Documentation Team in the [https://go.kde.org/matrix/#/#kde-docs:kde.org #kde-docs channel on Matrix] or Libera Chat, and written discussion is held over the [https://mail.kde.org/mailman/listinfo/kde-doc-english kde-doc-english mailing list].
You can chat with the Documentation Team in the [https://go.kde.org/matrix/#/#kde-docs:kde.org #kde-docs channel on Matrix] or [irc://irc.libera.chat/kde-docs Libera Chat], and written discussion is held over the [https://mail.kde.org/mailman/listinfo/kde-doc-english kde-doc-english mailing list].


You can chat with the KDE Web Team in the [https://go.kde.org/matrix/#/#kde-www:kde.org channel on Matrix] or Libera Chat, and written discussion is held over the [https://mail.kde.org/mailman/listinfo/kde-www kde-www mailing list].
You can chat with the KDE Web Team in the [https://go.kde.org/matrix/#/#kde-www:kde.org channel on Matrix] or [irc://irc.libera.chat/kde-www Libera Chat], and written discussion is held over the [https://mail.kde.org/mailman/listinfo/kde-www kde-www mailing list].


Learn more about [[Matrix]], [[Internet Relay Chat | Libera Chat]] and [http://kde.org/support/#mailinglists Mailing Lists].
Learn more about [[Matrix]], [[Internet Relay Chat | Libera Chat]] and [http://kde.org/support/#mailinglists Mailing Lists].

Revision as of 16:19, 30 March 2023

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. It links to the Typographical Guidelines, Tasks and Tools, and the Toolbox.

The contribution model works like so: you add the content first, and then someone else can review it. If you want to discuss an addition that was made or will be made, you can use that wiki page's Discussion section.

It is most often done in collaboration with the KDE Web team. We have an issue tracker for it.

Warning

The Techbase wiki is going away as soon as its content is ported elsewhere. Please consider contributing to Userbase, Community or Develop instead. If you'd like to contribute to porting the content from Techbase, we have an issue with tasks you can work on.


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

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 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 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:

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:

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