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 doc.suse.com 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.
Improved clarity and fixed typos.
Brought Style Guide into better compliance with itself using the style checker tool.
Moved Section 6.9, “Headings” from Section 7, “Structure and markup” into Section 6, “Language”. Added new section Section 7.15, “Outline levels and sectioning” with the information on structure that the former Headings section contained.
Split existing section Abbreviations into Section 6.1.2, “Latin abbreviations” and Section 6.1.3, “Units of measurement”. Added Section 6.1.2, “Latin abbreviations”,Section 6.1.3, “Units of measurement”, and Section 6.1.1, “Acronyms” to newly created Section 6.1, “Abbreviations”.
Separated list items for id attribute
and title in Section 7.16, “Procedures”.
Split the table in Appendix A, Terminology and general vocabulary into Section A.1, “Terminology” and Section A.2, “General vocabulary” to better reflect the roles of the terms listed there.
Updated terminology and general vocabulary tables in Appendix A, Terminology and general vocabulary.
Added entries for adapter, architecture, create a hard link, create a symbolic link, connect via SSH, init script, installation medium, log in via SSH, remove at runtime, solid-state drive, SSD, symbolic link, synchronization, synchronize, UEFI, Unified Extensible Firmware Interface, virtualize, WLAN, with regard to.
Changed accepted spellings from Wi-fi to Wi-Fi, Wi-fi card to Wi-Fi card, and Wi-fi/Bluetooth card to Wi-Fi/Bluetooth card. This matches the correct spelling of the brand.
Corrected rejected terms in the entry of AOO.
Added rejected terms to the entries of boot disk (“boot disc”), check box (“checking option”), flash disk, hard disk, hotplug (“hotadd”, “hotswap”), hotpluggable, hotplugging, press, slider (“slidebar”).
Removed “installation media” from rejected terms of installation source.
Improved alphabetical sorting.
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, OpenOffice.org, 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.
Restructured large parts of the style guide
Removed Creating a Consistent Structure: Lessons for Lizards section.
Renamed Creating a Consistent Structure: Official SUSE
Manuals to Outline of a Manual and
promoted to a <sect1/>.
Split the chapter Writing and Editing into Section 6, “Language”, Section 7, “Structure and markup”, and Section 9, “Managing documents”. Moved the subsections of Writing and Editing where they fit best.
Integrated the Markup appendix into to Section 7, “Structure and markup” and Section 9, “Managing documents”.
Moved Section 7.16, “Procedures” (formerly Creating Procedures) and Section 7.4, “Command-line input and command-line output” (formerly Presenting Computer Elements) as subsections into Section 7, “Structure and markup”.
Renamed Discriminatory Language to Section 6.2, “Biases and inclusiveness”.
Renamed Keys to Section 7.14, “Keys and key combinations” and promoted it to a <sect2/> within Section 7, “Structure and markup”.
Renamed GUI Elements to Section 6.22, “User interface items” and promoted it to a <sect2/> within Section 6, “Language”.
Created Section 9, “Managing documents” and moved Section 9.1, “Remarks”, Section 9.2, “XML comments”, and Section 9.3, “Entities” as subsections into it.
Moved Appendix A, Terminology and general vocabulary and the copyright notice into separate DocBook files.
Restructured terminology list, added more terminology
Renamed Spelling Terms to Appendix A, Terminology and general vocabulary and moved it into an appendix.
Centralized much of the information in the introductory paragraph of Spelling Terms in Section 6, “Language”.
Change table layout from two columns (“Word or Phrase” and “Usage Guideline”) to three (“Accepted”, “Rejected”, and “Usage Guideline”).
Added prefix (to) to all verbs.
Added grammatical classification of word to all entries.
Added entries for (to) activate sth., add-on, advice, (to) advise, after, although, and, appendixes, Audio CD, because of, basically, (to) boot using/via PXE, Btrfs, but, CD, CD-ROM, CUPS, (to) close sth., computer*, configuration, (to) configure, could, Common Unix Printing System, (to) deactivate sth., dialog, directory, DVD, e-book, EPUB, easy, easily, end user, etc., Ext3, Ext4, flavor, flash disk*, graphical user interface, HTTP, if, indexes, initialization, (to) initialize, IPv4, IPv6, license, (to) license sth., lowercase, just, need to, might, (to) multitask, must, obvious, obviously, openSUSE, (to) open sth., open source, (to) print sth., (to) preconfigure sth., preconfigured, (to) press sth., PXE, PXE boot, (to) quit sth., (to) register, (to) register at sth., (to) register for sth., SLE, SLED, SLES, SUSE Cloud, SUSE Linux Enterprise, SUSE Linux Enterprise Desktop, SUSE Linux Enterprise Server, SUSE Manager, SUSE Studio, self-evident, self-evidently, scrollbar*, simple, simply, (to) select sth., (to) shut sth. down, shutdown, (to) start sth. up, TAR archive*, (to) type sth. (into sth.), usage, Unix, uppercase, when, want sth., Wi-fi*, and YaST.
(An * marks potentially interesting changes.)
Changed accepted spellings of compund words whose second part is “name”. These are now written with a space: file name, host name, path name, user name.
Changed accepted spelling from screen shot to screenshot.
Switched from Merriam-Webster Collegiate Dictionary to https://www.merriam-webster.com/ Web site as the authoritative source of spellings.
Added Section 7.4.5, “Prompts” to document how to use prompts
in <screen/> elements.
In Section 3, “Names of example items”, added Geeko, Foxkeh, Konqi, and Duke to the list of mascots to choose from.
Removed all occurrences of “basically” and “stuff”. Removed other occurrences of colloquial language.
Updated various examples to use newer software versions or to not specify a software version. (Examples are soffice to loffice, SUSE LINUX 9.1.4.2 to SUSE Linux Enterprise).
Shortened and clarified many parts of the style guide to avoid tautologies and unnecessary explanations.
Rewrote large parts of Section 4, “Outline of a manual”. Removed example of structure. Added copyright notice as an example. Expanded on information needed for title pages and imprints.
Removed differentiation between the many types of
authors files from Section 4, “Outline of a manual”.
This was too complicated to be practical. Also, current practice is to
never mention translators.
Added “Objective before Instruction” rule to Section 6.17, “Sentence structure”.
Added short guideline about file extensions to Section 6.8, “File and directory names”.
Reworked Section 7.10, “Figures” to be more structured and added instructions for preparing and editing screenshots.
More informative example in Section 7.11, “Glossaries”.
Simplified rules for creating IDs in Section 7.12, “Identifiers”. The aim is to shorten the length of the average ID and to help to create predictable IDs.
Added the co prefix to Table 6, “Abbreviations for different elements in an
xml:id
attribute”.
Added this list of changes as an appendix.
Added list of authors as a separate DocBook file.
Added standard entities as a separate file.
Updated copyright notice to refer to SUSE, LLC instead of Novell, Inc.