m (1 revision: Moving Docbook Primer from UserBase to TechBase) |
|||
| Line 1: | Line 1: | ||
<languages /> | <languages /> | ||
| + | {{Transferring}} | ||
<translate> | <translate> | ||
| 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 |
As part of the wider KDE project, there are some things that documentation writers need to be aware of. There are a large number of other developers working on KDE, and working together with all of them is an important part of what we do.
String freezes, when we write, etc
| Warning |
|---|
| This needs reviewing by someone who pays more attention to releases than I do. |
The KDE release process, in which we go from the fast-moving and sometimes unstable world of the KDE svn repository, to a stable, polished product, is never exactly the same twice, but there are some common features:
A schedule for the next release of KDE is published at techbase.kde.org, with the definitive guide to what will be happening and when. There will be two or more "freezes", when changes of a certain type are not allowed in the KDE repository:
One important and fun part of working on KDE is the community of other developers who you work with. The people you'll work with most often as a documentation writer are the documentation team, the quality team (if you're a new contributor) and the maintainer of the application that you're working on.
The documentation team is your main resource for help with doc writing and a central point of contact to ensure that everyone's work is co-ordinated. The main ways to contact the documentation team are via the kde-doc-english@kde.org mailing list and on IRC in the #kde-docs channel on the server irc.freenode.net. If you plan to work on a particular application, please tell us, so that we can ensure that no-one else is working on it simultaneously, so that effort would be duplicated. Also, feel free to contact us with any problems or questions you might have about writing documentation. You don't need to feel like you're working entirely on your own – there are plenty of people who are able to help.
The KDE Quality Team provides more broad support. If you have any general questions about KDE development, or how documentation fits into the wider KDE environment, the Quality Team mailing list is a good place to ask: kde-quality@kde.org. If you're not sure whether to ask a question on the kde-quality or kde-doc-english list, just pick one and ask. Many people who read one list read the other, and you'll be pointed to the appropriate list if necessary.
Working with programmers is a little less formal. The usual reason to contact a programmer is to ask about a feature or behavior of an application that you're documenting. To find the appropriate person to contact for a particular application, look in the menu item for the maintainer. If you cannot find a maintainer, ask on kde-doc-english@kde.org or kde-devel@kde.org. If asking on the kde-devel list, mention that you're writing the documentation for that application – it helps to identify you to those reading a busy list. In general, programmers and other developers are happy to help, and willing to work with you, so don't feel afraid of asking them for information, and building up a working relationship.
With the pace of change of KDE applications, documentation can rapidly become out-of-sync with the application it is describing. To keep its value, documentation needs to be updated. Often this is simply a case of reading the existing documentation, and checking each description of an item against the latest version of the application. For example, are there new items in the menus that are not described in the documentation?
Sometimes, more extensive updates are needed. If new features of the application significantly change the way it works, then new sections of the documentation may be needed, or reorganization of the existing content might be necessary. In particularly severe cases, an entire rewrite might be necessary.
KDE uses the FDL (Free Documentation License) for all documentation. This license has several variants, some of which place restrictions on how content is used in other contexts.
The specific terms we use are:
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1. or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.
This is the only version of the license that is safe to use for documentation that is to be distributed with KDE.
The items that may differ in other uses of the FDL are as follows:
| Warning |
|---|
| The terms of the FDL as used by KDE documentation, are entirely GPL compatible, and do not restrict the reuse of the content. Any deviation from these terms, or any change in license could restrict distribution of your software or documentation, and should only be undertaken with full knowledge of the consequences, and with written permission of all copyright holders. |
The KDE bug tracking system, located at http://bugs.kde.org, is now part of the documentation team's toolkit. Issues with the KDE documentation can be filed in the "docs" product of the bug tracker. Incorrect or outdated content, missing content, outdated screenshots and typos are all appropriate reasons to file bugs.
When filing bugs, especially for incorrect or outdated content, be specific about what's wrong. For example, if a certain page of a configuration dialog is incorrectly documented, say which page it is in the bug report. That way, someone fixing the bug can quickly find the appropriate part of the application and the documentation, and make the necessary changes with a minimum of effort.
For more information on using the KDE bug tracking system, see Bug And Wish Reports Management.
KDE TechBase 
