The KDE Documentation Primer

The KDE Documentation Team

Carlos Woelz

Revision 0.02 (2005-05-21)

This document tells you everything (hopefully!) you need to know to start writing documentation for KDE. Please report any errors or omissions to .


Table of Contents

1. Introduction
2. Getting Started
Things You'll Need
English Knowledge
Deciding 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: Procedures and Tools
Getting the Documentation Sources
Working with plain text sources
Retrieving the DocBook sources
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 the Sources with Subversion
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