KDEdu Logo

Documentation Tutorial

Basic Rules

Application documents should be stored in a directory under modulename/doc/ (where modulename usually is kdeedu) and they should just be the English documents. For example, if your application is called app, the documents should be in modulename/doc/app/. As many developers may wish to write their documents in their mother-tongue, it is important that they arrange to have an initial translation to English. Please contact the kde-edu@kde.org mailing list for assistance in arranging this.

What should be in this directory?

There are certain requirements for KDE documents, and the first one is that they are written in "docbook XML" format. DocBook is a variant of XML, and is the format used by all KDE documents. If you were intending to write plain text instructions, or even HTML, these are sadly not appropriate. If you have written the document in HTML format, we can probably help you convert it to DocBook format. The filename for the entire document should be index.docbook. If you use KDevelop, the document template there is exactly the right format to base your document on. Please go to [5] to see a list of the tools that can make your writing easier. Moreover, here[6] are some guidelines to help you get the right information in your documentation. If you have images to go in the documents, these should be in the same directory as your index.docbook file. Please don't put them in a subdirectory.
For guidelines on the size of files you should be using, please see [3].

Translations

When the documents are ready for translation, let us know, and we can arrange for them to be automatically passed to the internationalisation (i18n) team. Once the translations are ready, it is of course possible for application authors to take them for distribution separately.

Mailing lists

There are mailing lists for application authors who are writing their own documents. These are:

Things to remember

  • the documentation team can (and will) change around the text of documents to fit in with KDE rules. For example, they will ensure that Trademarks are acknowledged in order to protect the KDE Project from any potential legal issues
  • try to split your index.docbook file into different entities
  • make screenshots in the current theme, and following the guidelines [3], add screenshots in the same dir than the docbook file(s)
  • try to find an English native person that will proof-read your doc and adjust the terms. You can ask the Quality Team for that. If your application is related to a specialized field such as Chemistry or Mathematics, try to find someone with the required knowledge
  • Run the English spell-checker
  • Run meinproc --check index.docbook from the console using the latest kdelibs to check if your doc is correctly parsed and to check that the document is as you want

Special Needs

If you have user documents with special needs (for example large clear text, suitable for small children), please let us know and we will try to help.

Releases

Normally, when a KDE release is due, there will be a two month "feature freeze", where no new features should be added to applications. There is also a shorter "message freeze", where the only messages that should be changed should be related to bug-fixes. Even then, these messages may not end up being translated due to time pressures on the i18n teams. Please, be sensitive to the pressures on other teams.
  1. The KDE DocBook Authors Guide: a quick reference guide to the current KDE DocBook markup standards
  2. The KDE Documentation Primer: how to start writing documentation for KDE
  3. The Screenshot Guidelines: how to take correct screenshots to include in your documentation
  4. The KDE style guide: tips and hints on writing correctly
  5. Tools to improve the writing of documentation
  6. Documentation about hot to improve the contents of your documentation



Last update: 2014-07-29

Global navigation links