Applies to 2024-10

4 Outline of a manual #

Maintain a consistent structure within your documents. The structure can vary between different books, articles or projects, but the most common parts of the document structure are documented here.

4.1 Books #

For books, use a document structure that includes the following elements, in that order:

a preface
chapters, split into sections
(optional) a glossary
(optional) appendixes

For books with many chapters, create parts at the outline level above chapters.

Title page and imprint

Both title page and imprint are created automatically, but depend on information being present in the book.

Title. Work with the product manager to define the book title. The book title should not contain the product name and version.
Product name and product version. Work with the product manager to find the correct product name and version number. Mark this information up with <productname/> and <productnumber/>, respectively.
Documentation version or revision information. Optionally, use the <releaseinfo/> element to mark up version or revision numbers of the documentation itself.

Copyright notice. Use the standard copyright notice reproduced below. Change the starting year of the copyright protection to the current year.

Example 4.1: Standard copyright notice #

<legalnotice>
 <para>
  Copyright &copy; [starting year]&ndash;<?dbtimestamp format="Y"?>
  SUSE LLC and contributors. All rights reserved.
 </para>
 <para>
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.2 or
  (at your option) version 1.3; with the Invariant Section being this
  copyright notice and license. A copy of the license version 1.2 is
  included in the section entitled <quote>GNU Free Documentation
  License</quote>.
 </para>
 <para>
  For &suse; trademarks, see
  <link xlink:href="http://www.suse.com/company/legal/"/>.
  All other third-party trademarks are the property of their respective
  owners. Trademark symbols (&reg;, &trade; etc.) denote trademarks
  of &suse; and its affiliates. Asterisks (*) denote third-party
  trademarks.
 </para>
 <para>
  All information found in this book has been compiled with utmost
  attention to detail. However, this does not guarantee complete
  accuracy. Neither SUSE LLC, its affiliates, the authors nor the
  translators shall be held liable for possible errors or the
  consequences thereof.
 </para>
</legalnotice>

Abstract

Use an abstract to summarize the information provided in a book, article, chapter, or set in 70–150 characters. Do not use lists, images or examples in an abstract.

Example 4.2: An abstract #

Perform an upgrade of a SUSE Linux Enterprise system to a new major version in environments which do not allow for standard booting of the installation.

Table of contents

The table of contents is generated automatically.

Preface

Include a brief overview of the content of a manual, related manuals and typographical conventions. The preface can also contain information about its target audience.

Parts

If you are writing a book with many chapters, create parts at the outline level above chapters. Parts should contain at least three chapters. Keep part titles clear and concise. Often a single noun is enough. Typical part titles are Installation or Network.

Chapters

Chapter titles should not contain product version numbers which affect the output of data analytics. Chapters typically consist of the following elements (appendixes should be regarded an exception):

Abstract. In an abstract, summarize the topic instead of summarizing the outline. See also Abstract.
Introduction. Provide introductory information directly after the abstract. Do not place it in a separate section.
Sections. Structure the detailed information, so readers can skim the text. Create sections for every major task, such as installing, configuring, monitoring, and administering. If helpful, split sections into subsections. Avoid nesting deeper than three levels of sections.
Start sections with an introductory paragraph outlining the focus of the section. If the section describes a sequential task, add a procedure description, as discussed in Section 7.16, “Procedures”. Steps of a procedure can contain a cross-reference to subsections where topical background is provided and an action is explained in detail. See also Section 7.5, “Cross-references”.
Troubleshooting. In this section, collect common mistakes and problems. The section should always be named Troubleshooting. Use the DocBook element <qandaset/> (a Question and Answer section) to mark up Troubleshooting problems. In case you want to describe solutions to more than ten problems, add topical subsections ( <qandadiv/> elements) below the Troubleshooting section.
More information. In a section named More information, collect Web links to all sources of information that might prove helpful in a given context. Follow the general referencing guidelines in Section 7.5, “Cross-references” when creating such sections.

Glossary

The optional glossary contains important terms in alphabetical order and provides a brief explanation for each. For more information on creating lists of terms, see Section 7.11, “Glossaries”.

Contributors

Writing documentation is a collaborative effort. To give credit to all contributors, add an appendix to the guides which points to the Contributors page for the respective GitHub repository. For an example, see Appendix B, Contributors.

For articles and small documents (such as SUSE Best Practices) whose content is created and maintained by five or fewer contributors, all of whom are from outside the documentation team, credit the contributors on the title page.

The above are a minimum. In addition, make sure that the contributors appendix is compliant with the document license.

4.2 Articles #

For articles, use a document structure that includes the following elements, in that order:

introduction
sections, split into subsections
(optional) a glossary
(optional) appendixes