Getting Started - The KDE Documentation Primer

 |  The KDE Documentation Team

Getting Started

If you got this far reading this document, you're probably interested in helping with KDE documentation. If so, welcome aboard! We're always happy to have new contributors, and whatever your skills, you can help make KDE even better.

Things You'll Need

To write documentation, there are only three things that are absolutely necessary: some English knowledge, knowing what you want to document, and access to a relatively recent version of the application you want to document.

English Knowledge

All KDE documentation is originally written in English, so you have to be able to write English to a reasonable level. That said, you do not need to be a native speaker, and you do not need to write word-perfect English. There are native English-speaking proofreaders on the documentation team, and we would much rather have some documentation that needs a little tweaking, than no documentation at all. If you do not feel comfortable writing in English, you might like to contribute to one of the KDE translation teams. You can find more information about translation on http://i18n.kde.org.

If you're a fluent English speaker with an eye for detail, you might be interested in joining the proofreading team. Just drop an email to kde-doc-english@kde.org if you'd like to help the proofreaders.

Deciding What to Write About

KDE is a very large project, with many different parts and programs. Because of this, it can be hard to know where to start if you want to contribute. There are a few rules of thumb that can help you decide what to write about:

  • Find a topic that you will enjoy writing about; It will increase your motivation and help you to produce better documentation.

  • Write about an application you know well. You'll be able to spend more time on writing and less time trying to work out how the application works. On the other hand, documenting an application can be a good way to learn about how it works, especially if you like a challenge!

If you are looking for an application to document, or just checking the status of the application you want to work with, the Docbook health table contains lists of applications, organized by modules, and their documentation status.

If you start documenting one of the listed applications, please announce this on kde-doc-english@kde.org. But If you just can not find an application to work with, write to kde-doc-english@kde.org and ask for suggestions. There's always something available to do, but there's no obligation to work on a particular application. Also, contributing to a document doesn't force you into keeping that document up-to-date (although if you can do that, it is very welcome!).

Another place to check is the KDE bug list at http://bugs.kde.org. This provides a place to list specific small changes that are needed to documents. These are often nice small jobs to get you started contributing. A set of quick links to ready made queries are available from the Documentation Project's http://i18n.kde.org/doc/current.php page.

It is also helpful to the team to file more bugs like these above. You will need a bugzilla account, and a recent copy of KDE. Simply open an application, choose Help > <appname> Handbook. Then just read through the document, following along in the application. KDE applications are a moving target to document, and sometimes the documentation has not yet caught up with a change to the interface or behavior of an application. Feel free to file bugs for any of these issues you find, in order of urgency:

  • Inaccurate information about how an application works

    For instance, if you previously needed to save changes to a file before they take effect in the GUI, and this now happens automatically, text referring to manual saving should be removed, or it will confuse readers.

  • GUI options or menu items (or sometimes, entire dialogs)

    This often happens in configuration dialogs, when new items are added, a new grouping of existing options may be created.

  • New Features that are available and are not yet documented.

Access to a Recent Version

To make sure that the documentation you write is up-to-date, you will need to run a recent version of the application you are working with. This normally means a recent beta version, a version of your application compiled from sources or a version of KDE compiled from sources in the Git repository. If you think that compiling from sources is too burdensome, and you cannot get some recent beta packages, there are still some interesting possibilities to work around this requirement:

  • Write about a stable application: there are many apps with a stable interface which are still lacking good documentation. In this case, the last stable version provided by your distribution will be sufficient to write about it, no compiling required.

  • Use live images provided by KDE Neon.

If you want to try out building KDE from sources, Build from source will tell you how to use anonymous Git to install the snapshot you need to write KDE documentation.

Article contributed by , , , and under the GFDL-1.2-or-later license.