Documentation Primer/Manual/Publishing

Jump to: navigation, search
Other languages:English 100%

Contents

Sending the New Documents and Changes to KDE

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.

Respecting the Release Schedule

String freezes, when we write, etc

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

Feature Freeze
When feature freeze is active, developers are not allowed to commit new features to the repository. This is a good time to start writing, since the features available in the application during this period are the same as the ones which will be available in the released version.
String Freeze
Text strings appearing in the KDE user interface and in the documentation are not allowed to be changed. This is to allow translators to provide thorough translations which will match the release. We are still considering how to work during this period of freeze. One method which we have tried is to continue writing, but hold back all changes to be committed in one go, immediately before the release.

Working With Other Documenters and Developers

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 Help -> About KApp 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.

Updating Documentation

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.

Licenses for KDE Documentation

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:

with no Invariant Sections
Invariant sections are, as you might expect, sections that must not be altered in any reproduction of the content. The reasoning behind this, is so nobody can make a subjective claim, and attribute it to you, by altering your words.

For instance, if you say "Foo is a terrible piece of software" and the section is marked invariant, the developers of "Foo" cannot take your writing, change it to say "Foo is a great piece of software" and still attribute that opinion to you.

For many people, this restriction is incompatible with the GPL and therefore some distributions choose not to include any user manuals that contain "Invariant Sections". Since they must be reproduced verbatim, this also means we are not able to reuse such content in our own manuals, without including this statement.

For this reason, "Invariant Sections" are not permitted in documentation that is to be distributed with KDE, nor can we safely reuse content from other sources, if they include Invariant Sections.

It is not normally appropriate to write opinion pieces in KDE documentation. Such content should be restricted to your own website, or documentation that is not distributed with KDE, so the fact we outlaw "Invariant Sections" in KDE documentation is not normally a problem. If you think you have a special case, please raise it with the documentation team, and understand that including such sections may prevent some distributions adding your manual (or the software itself) to their distribution.
with Front-Cover Texts names of sections, with Back-Cover Texts names of sections
As with "Invariant Sections", these are texts that may not be altered, and must be included in any reuse of any of the content. It also means we would have to alter our license to match that of the content we have reused. This leads to similar problems as that of the "Invariant Sections".

This one mainly comes up if we want to use FDL content found from other sources (for instance, books or websites.) In these cases, the best approach is to ask the authors to permit relicensing, and offer to include their front/back cover texts anyway, but without having to change our license terms.
noframe
 
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.

Using bugs.kde.org

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.


This page was last modified on 9 September 2012, at 11:10. This page has been accessed 1,163 times. Content is available under Creative Commons License SA 3.0 as well as the GNU Free Documentation License 1.2.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal