Revision History: SUSE Documentation Style Guide


  • Added a new section on Profiling to the Structure and markup chapter.

  • Updated the introduction to Structure and markup with links to doc-kit that now hosts examples of rendered books and articles.

  • More in Structure and markup: links to READMEs in doc-modular to find naming conventions for file and figure names, and guidelines for using the <xrefstyle/> attribute—only use the tags <select:/> and <template:/> with it to customize cross-links.

  • Added clarified reference on using entities to create generic names in the Names of example items chapter, with the link to doc-kit.


  • Created a new Revision history that opens as a separate file and is linked from the main doc. Added info about this in the Smart Docs chapter: Use the <revhistory/> tag in the <info/> part of XML file.

  • Updated the rules for creating glossaries in section Glossaries, which also contains an example of the specific structure that must be used. A style sheet update now supports the automatic alphabetical ordering of items.

  • Updated the Structure and markup chapter: Use the <href/> element to provide cross-references only within the same doc set; the tag <citetitle/> is not translated and must only reference names of printed books (section DocBook tags, Inline elements).


  • Updated the chapter on AsciiDoc: sorted the recommendations and added the link to the guidance on AsciiDoc in Technical Reference Documentation.

  • Updated the Language chapter with info on product names. If a product name is not in the style guide's Terminology table or in the entities Doc Kit file, refer to the official SUSE Products page and the Marketing department. Do not use articles in front of product names.

  • New items in the Terminology table: since rejected in the meaning of because; timeout and system-wide added as approved terms. Data only requires singular, so data is is approved and data are is rejected.


  • Added a new chapter on Smart Docs, describing the principle, the structure and its building blocks.

  • Updated the recommended minimal title length with 29 characters for SEO purposes.

  • Updated the Inline elements table in the DocBook Tags chapter: added the guidance to use the secure protocol prefix https:// and to use the package tag to replace systemitem class="resource".

  • Added information on the use of the formalpara tag.

  • Added information about the element phrase role="style:sentencecase" for the style sheets to expand the relevant entities as uppercase, when needed.

  • Updated the Terminology table with drop-down list, list box and right-, left-, middle click.


  • Finalized the file and image naming conventions and provided a reference to the doc-modular repository in the Structure and Markup chapter.

  • Added rules for quotation marks in chapter Language only use them in quotes; in other cases, use the emphasis element to make words or phrases more conspicuous.

  • Added the guidance to avoid using single quotation marks.

  • Updated the Structure and Markup chapter with the instruction to not use articles before book and chapter titles when referencing them.

  • Updated rules for the line length (100 char now) and indentation (2-space characters now) in section Formatting XML.

  • Clarified the usage of the term register to/with in Terminology.


  • Added new content, updated and restructured the content of the Cross-references section (a warning not to include xref elements into titles).

  • Updated the Screens subsection with the info on automatic syntax highlighting.

  • Expanded the rule of using the comma - no use of comma in simple series like x, y and z.

  • Described how you can group different callouts to point to the same annotation in the text (helps avoid repeating the same annotation).

  • Updated chapter Language with punctuation rules for quotation marks - commas and periods go inside them per AE punctuation rules.

  • Added terms: unit, unit file, console, shell, terminal, init script, and whitespace.


  • Added new content on the correct use of URL in the ‘External links to SUSE documentation’ subsection

  • Added general instructions on how to create and style tables in the section ‘Structure and markup’

  • Added a subsection about hyphens to the ‘Language’ section

  • Added and updated terms and definitions: ‘bare metal’, ‘drop-down list’, ‘list box’, ‘screen’, ‘usage’, ‘utilization’, ‘view’, ‘multi-version’ (adjective)


  • Added a section on localization-friendly writing in the 'Web writing' chapter

  • Added a section on creating SP-independent links to the chapter ‘Structure and markup’

  • Added definitions of program, application, script, command, tool, form, dialog

  • Updated the 'DocBook tags' section of the style guide (fixed typos and layout)

  • Added specification on the use of the % sign

  • Added admonition about version numbers in chapter titles

  • Rearranged sections in "Structure and markup chapter" in alphabetical order

  • Added terms 'codestream', 'crash dump'

  • Updated guidance on punctuation to use at the end of list items


  • Updated the Abstract instances in Style guide

  • Updated the chapter abstract wording and the example of an abstract to match the char limit.

  • Added a section on Web writing and SEO-friendly content

  • Added a section on Tech writing to replace the Audience section

  • Added a section about DocBook tags allowlist

  • Added terms: 'changelog', 'real time', 'coldplug'

  • Minor bug fixes of the style guide


Updated recommendations for <abstracts/> and <highlights/>: Always add an abstract to chapters, with a length of 70 and 150 characters. Do not use <highlights/>.


  • Updated recommended prompt style: Where possible, use short prompts such as or .

  • Updated the definitions of installation medium and installation source to clarify that installation medium should only be used where a physical medium is concerned.

  • Added rules for when multiple commands can be combined within a single <screen/> element.


  • Updated the spelling of lifecycle (former spelling, life cycle).

  • Updated recommendations on how to list contributors. Change Contributors appendix accordingly.

  • Mentioned that placeholders must not contain spaces.


  • Updated the standard title for sections comprising of references to other documents from For more information to More information.

  • Mentioned Doc Kit default entity file.

  • Added examples for hyphenation and file names/directory names.

  • Clarified/shortened/reformatted various language advice. Improved wording consistency of references to other sections of the guide.


  • Mentioned that we support the Inclusive Naming Initiative.

  • Added section about rules for linking to external sites.

  • Added a section about avoiding promises of future features.

  • Mentioned that UI labels should always be capitalized as they are capitalized in the UI.

  • Clarified section about abbreviations.

  • Improved structure of capitalization section.


  • Updated the Style Guide to recommend the use of sentence case for titles. Book, article, and set titles are to remain in title case.

  • Added guideline when to use noun-based and when to use verb-based headings.


  • Explained issues with URL shorteners.

  • Clarified section on creating IDs by removing confusing left-overs from description of former .-based ID scheme.

  • Clarified and updated section about entities. Entities are not used during translation.

  • Updated XInclude section. XIncluded documents can also be plain-text.

  • Updated formatting of XML examples across the document to 1-space indent, as is encouraged in the XML formatting section of this document.

  • Removed Indexes section. There has not been a practical use of this section in several years.

  • Updated advice on lists. Deduplicated the sections about lists in the Structure and Markup section versus the section in the Language section. Aligned list terminology with DocBook terminology.

  • Improved phrasing and fixed minor language and technical errors across the document.


  • Removed outdated and overly specific recommendation to use Shutter application from section Screenshots.

  • Clarified section Outline. Included better guidance for article outlines. Clarified when to contact product managers. Removed outdated reference to SVN metadata.

  • Updated URLs of DocBook Definitive Guide. Updated URLs to HTTPS.

  • Moved advice to include at least introductory content in each section from Language/Headings section to Structure/Outlining section.

  • Clarified that admonition titles should use title style.

  • Removed listing of document authors.

  • Made language fixes, clarifications, and added explanations.


Added guidance regarding appropriate on-page screenshot sizing.


Added minimal guidance regarding AsciiDoc documents.


Updated guidance regarding use of . and _ in XML IDs.


Added guidance regarding easily outdated information in screens and screenshots.


  • Added terminology entry for subsystem.

  • Improved guidance regarding numbers and measurments.


Improved guidance regarding path names.


  • Added guidance regarding XML formatting.

  • Improved guidance regarding commands.


  • Documented ID prefix for prefaces.

  • Added guidance regarding scaling of screenshots.


Added terminology entry for namespace.


Improved guidance regarding XML IDs.


Updated terminology entry for IBM Z.


Added terminology entries for e-mail, hot key.


  • Added terminology entries for use case, business case.

  • Improved guidance regarding use of prompts.

  • Added guidance regarding list structure.


Corrected SLES for SAP Applications product name.


July 2016 Major Update Version 2016-07 was a major update focused on adding terminology, fixing errors, and making the guide DocBook 5-compatible. Version 2014-02.2 was released on 2016-07-01.

  • Migrated style guide from SVN to Git. Migrated style guide from DocBook 4.3 to DocBook 5.1. Switched to using profiling instead of two MAIN files for being able to customize contents based on the DC file. Added Report Bug link.

  • Updated style guide for use with DocBook 5.1 and GeekoDoc.

  • Improved clarity. Fixed typographical and grammar issues. Brought Style Guide into better compliance with itself using the style checker.

  • Updated legal notice reproduced in Section 4.1, “Books”.

  • Added Section 6.15, “Quotations”.

  • Added Section 7.4.6, “Screens”. Removed some now-duplicated content out of Section 7.7, “Examples”.

  • Corrected syntax of Example 12, “Example of a figure”: <textobject/> must be within <mediaobject/>.

  • Updated terminology and general vocabulary tables in Appendix A, Terminology and general vocabulary.

    • Added entries for AArch64, AMD64/Intel 64, cursor, for instance, IA64, kernel space, KIWI, live CD, live DVD, live image, pointer, POWER, Samba, SUSE Enterprise Storage, SUSE Linux Enterprise Server for SAP Applications, systemd, System V init, technology preview, toolchain, user space, Web cam, x86, z Systems, words with -ward (such as afterward or backward),

    • Changed accepted entry from SUSE Cloud to SUSE OpenStack Cloud. Updated rejected entries.

    • Improved definitions of click and press.

    • Added mask as a rejected entry to dialog. Added a definition for dialog.

    • Removed duplicate entry EPUB.

    • Improved alphabetical sorting.


Version 2014-02.2 was a minor update focused on adding terminology and fixing small errors. Version 2014-02.2 was released on 2014-04-24.


Version 2014-02.1 was a minor update focused on adding terminology and fixing small errors. Version 2014-02.1 was released on 2014-03-13.

  • Improved clarity and fixed typos.

  • Improved example of a warning in Section 7.1, “Admonitory and advisory paragraphs”.

  • Added an instruction where to insert screenshots to Section 7.10.2, “Screenshots”.

  • Updated terminology table in Appendix A, Terminology and general vocabulary.

    • Added entries for AOO, Apache OpenOffice, Bluetooth, Bluetooth card, drop-down box, Ethernet card, HTML page, HTTPS, KDE, LibreOffice, Linux, list box, menu,, OOo, please, delta RPM, (to) save sth. (with sub-entries), selected, terminate, text box, Wi-fi card, Wi-fi/Bluetooth card, (to) write sth. and video DVD.

    • Replaced entry for facilitate with entry for simplify.

    • Added HTML web page as a rejected entry to Web page.

    • Added joker as a rejected entry to wild card.

    • Added screen as a rejected entry to dialog.

    • Removed graphical UI as a rejected entry from GUI and graphical user interface.

    • Clarified usage of (to) close sth., (to) log in, (to) log out, and (to) quit sth..

    • Changed accepted entry from Audio CD to audio CD.

    • Removed entries for computer and Kernel.


February 2014 Major Update

2014-02 was a major update focused on restructuring the style guide and adding terminology. Version 2014-02 was released on 2014-02-18.