SUSE Documentation Style Guide #
This guide provides answers to writing, style and layout questions commonly arising when editing SUSE documentation. The GeekoDoc and DocBook markup reference in this guide will help you choose the right XML element for your purpose. Following this guide will make your documentation more understandable and easier to translate.
- 1 Writing technical documentation
- 2 Documentation content
- 3 Names of example items
- 4 Outline of a manual
- 5 Writing for the Web
- 6 Language
- 6.1 Abbreviations
- 6.2 Biases and inclusiveness
- 6.3 Capitalization of headings and titles
- 6.4 Commas
- 6.5 Contractions
- 6.6 Dashes
- 6.7 End of sentence punctuation
- 6.8 File and directory names
- 6.9 Headings
- 6.10 Hyphens
- 6.11 Lists
- 6.12 Numbers and measurements
- 6.13 Possessives
- 6.14 Prefixes
- 6.15 Quotations
- 6.16 Semicolons
- 6.17 Sentence structure
- 6.18 Slashes
- 6.19 Tense
- 6.20 Tone and voice
- 6.21 Trademarks
- 6.22 User interface items
- 7 Structure and markup
- 7.1 Admonitory and advisory paragraphs
- 7.2 Application names
- 7.3 Callouts
- 7.4 Command-line input and command-line output
- 7.5 Cross-references
- 7.6 Emphasis
- 7.7 Examples
- 7.8 External links
- 7.9 External links to SUSE documentation
- 7.10 Figures
- 7.11 Glossaries
- 7.12 Identifiers
- 7.13 Lists
- 7.14 Keys and key combinations
- 7.15 Outline levels and sectioning
- 7.16 Procedures
- 7.17 Products
- 7.18 Profiling
- 7.19 Questions and answers
- 7.20 References to other external resources
- 7.21 Tables
- 7.22 User interface items
- 8 DocBook tags
- 9 Managing documents
- 10 Formatting XML
- 11 Working with AsciiDoc
- 12 Working with Smart Docs
- A Terminology and general vocabulary
- B Contributors
- C GNU Free Documentation License
- C.1 PREAMBLE
- C.2 APPLICABILITY AND DEFINITIONS
- C.3 VERBATIM COPYING
- C.4 COPYING IN QUANTITY
- C.5 MODIFICATIONS
- C.6 COMBINING DOCUMENTS
- C.7 COLLECTIONS OF DOCUMENTS
- C.8 AGGREGATION WITH INDEPENDENT WORKS
- C.9 TRANSLATION
- C.10 TERMINATION
- C.11 FUTURE REVISIONS OF THIS LICENSE
- C.12 ADDENDUM: How to use this License for your documents
- 7.1 Important elements
- 7.2 Elements related to
<callout/> - 7.3 Elements related to command-line input and output
- 7.4 Elements related to
<example/> - 7.5 Elements related to
<figure/> - 7.6 Abbreviations for different elements in an
xml:idattribute - 7.7 Elements related to lists
- 7.8 Elements related to
<keycap/> - 7.9 Elements related to
<procedure/> - 7.10 Elements related to
<qandaset/> - 7.11 Elements related to
<table/> - 7.12 Elements related to
<guimenu/>
- 4.1 Standard copyright notice
- 4.2 An abstract
- 6.1 Quote
- 7.1 An example of a warning (source)
- 7.2 Example of callouts (source)
- 7.3 Example of callouts (output)
- 7.4 Example of a callout group (source)
- 7.5 Example of a callout group (output)
- 7.6 Example of a cross-reference (source)
- 7.7 Example of a cross-reference (output)
- 7.8 Example of an example
- 7.9 Example of a figure
- 7.10 A typical example of a glossary
- 7.11 Examples of identifiers
- 7.12 Example of an itemized list (source)
- 7.13 Example of an itemized list (output)
- 7.14 Example of an ordered list (source)
- 7.15 Example of an ordered list (output)
- 7.16 Example of a variable list (source)
- 7.17 Example of a variable list (output)
- 7.18 Example of a key
- 7.19 Example of a keyboard combination
- 7.20 Example of a procedure (source)
- 7.21 Single profiling with the attribute
os - 7.22 DC file with profiling for SLES
- 7.23 Multiple profiling with attributes
osandarch - 7.24 Example of a questions-and-answers section (source)
- 7.25 Example of a table (source)
- 7.26 Example of a table (output)
- 7.27 Example of a single user interface item
- 7.28 Example of nested user interface items
- 9.1 Excerpt from
product-entities.ent - 12.1 Revision history example (source)
- 12.2 Revision history example (output)
Copyright © 2007– 2024 SUSE LLC and contributors. All rights reserved.
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 “GNU Free Documentation License”.
For SUSE trademarks, see https://www.suse.com/company/legal/. All other third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.
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.