The KDE Documentation Primer

The KDE Documentation Team

Carlos Woelz <carloswoelz@imap-mail.com>

Revision 0.01 (2004-08-22)

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.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. A copy of the license is included in the section entitled "GNU Free Documentation License".

This document tells you everything (hopefully!) you need to know to start writing documentation for KDE. Please report any errors or omissions to <kde-doc-english@kde.org>.


Table of Contents

1. Introduction
2. Getting Started
Requirements
English Knowledge
Defining What to Write About
Access to a Recent Version
3. KDE Writing Recommendations and Guidelines
Writing for your Audience
English Usage Guidelines and Recommendations
What to Include
4. Writing Documentation
Getting the Documentation Sources
Working with plain text sources
Retrieving the DocBook sources
DocBook Editors
Quanta
Kate
Emacs and Psgml
Checking and Viewing the Documents
Using checkXML
Using meinproc
5. DocBook Introduction
Overview
Content and Presentation
Structure
KDE Specialities
Entities
Necessary Sections
6. Sending the New Documents and Changes to KDE
Respecting the Release Schedule
Managing CVS
Checking Out: Getting a copy of the KDE source
Updating Your Sources
cvs commit: Making your changes available
Managing Conflicts and Other Problems
Working With Other Documenters and Developers
Updating Documentation
Licenses for KDE Documentation
Using bugs.kde.org
7. Leveraging your Newly Acquired Knowledge
8. Credits and License
A. KDE DocBook Reference
General KDE markup style guide
Purpose of this document
Other reference material
The Prologue
book and the bookinfo section
Chapters and Sections
The linking elements
Lists
Tables
The GUI elements, menus, toolbars and shortcuts.
Describing actions and commands
Questions and Answers
Images and Examples
General markup (not covered elsewhere)
Admonitions: Tips, hints, and Warnings.
The synopsis elements
Markup for programming
Making Callouts
References, indexes, and glossaries
Making a glossary
Making an Index
Other Reference Sections
Tags we do not use
Alphabetical List of all elements
Credits and License
B. Widget Names