Use chapters to break up the document into smaller chunks. A chapter break should occur when a major subject change happens. Use sections within the chapter when the subject changes, but you are still discussing a particular aspect of a larger subject.

For example, going from discussing how to use the application, to how to configure the application would be worthy of a new chapter. Moving from discussing how to specifically configure the application on SuSE, to how to specifically configure the application on Red Hat®, would be a new section in a larger “Configuration” chapter.

Chapters must have an id. This is the only attribute used in KDE documentation. For KDE Documents, this id must be in lower case, and with a hyphen (-) to separate words. Please don't use spaces, underscores, or run the words together. For HTML generation, the chapter id and most <sect1> id's are used to name the separate HTML pages, so take care to make them sensible and descriptive. For translators, these id's should be translated, but you will need to take care to also translate references to the id's in <link> and <xref> elements in other parts of the document.

Titles are used in many places, but the most common is the Chapter and Section headings. Make sure to use sensible titles, as these will also be that chapter's (or section's) entry in the table of contents, so people will rely on these to find the part of the document they are interested in.

Use sections to break chapters up into smaller pieces. Use similar criteria on where to divide them as you would for chapters.

Sections require a <title>. Sections are nested according to the number - a <sect2> can contain any number of <sect3>, which can contain <sect4>, but a <sect2> can't directly contain a <sect4>.

<sect1> requires an id attribute, and you can use id's on the other section tags if you want to later link directly to them from other parts of the document. id is the only attribute used in KDE Documentation.

The section info elements are rarely used in KDE Documentation. They are appropriate for documents where some smaller sections are contributed by third parties, or where the document covers multiple applications. The contents are more or less the same as those of the <bookinfo> section, although they tend to be briefer.

Please ensure if you use these elements that you add the translation placeholder comments as you do in the prolog.

The standard installation instructions for all applications are contained in an <appendix>, and are normally required for KDE documents. Although the installation instructions as found in the template are reasonably complete, and need no customization for most applications, authors are very strongly encouraged to expand on them. For example, links to web pages, where to find libraries, plugins, screenshots of the application in a particular configuration, or any other information you can think of.

If the application is only distributed with KDE, there is little use in repeating the same installation instructions for every manual. You may leave it out entirely, unless you have further information to add.

For other purposes, appendices are used infrequently in KDE Documentation. An appendix can be found, for example, in the KPPP document, containing such things as Hayes Modem commands. Only use an appendix if you think it's very necessary. In most cases, the information it would contain would be better moved to the main document. In the example of KPPP, this information is vital to a few people, but extremely uninteresting to the majority, so it was placed in an appendix.