Documentation Primer/Manual/Getting Started

Jump to: navigation, search
Other languages:English 100%
Dialog-information.png
 
Information
These pages are being transferred from UserBase. Please don't work on them until the transfer is complete, and the old UserBase pages have been removed.


Contents

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.

noframe
 
Note
Notice that the list of requirements does not contain a requirement that you learn DocBook, or any of the other tools we use. We're very happy to receive documentation written in plain text. We would much rather have the content and have to add formatting than have no content at all.

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 don't need to be a native speaker, and you don't 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 don't 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 l10n.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'll 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 KDE Documentation Health Table contains lists of applications, organized by modules, and their general status, including documentation status, and who is working on it. Not all modules and applications are up to date, but it is certainly worth checking.

If you start documenting one of the listed applications, please add your name to the wiki pages as well. But If you just cannot find an application to work with, write to 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's very welcome!).

Another place to check is the KDE bug list at bugs.kde.org. This is usually more detailed than the wiki, and 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://l10n.kde.org/docs//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 worksFor 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'll 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 svn and 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.

If you want to try out building KDE from sources, the KDE TechBase provides a detailed, step by step building guide.


KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal