Revision History: SUSE Documentation Style Guide

Updated the example of the Revision History entry (marked up with the <revhistory/> tag) in the metadata field of XML source documents.

Added the instruction to not use spaces around slashes in our texts.

Added an instruction in the subsection “DocBook tags” on when to use the <guimenu/> tag. It is used to mark up all GUI elements like button, label and menu.

Updated the instruction in “Sentence structure” and increased the word limit for a sentence to 25 words.

Updated the “Entities” subsection in “Managing documents”: common types of entities and their use cases, the Doc Kit repository that maintains official generic entities, creating custom entities, and entity files.

Updated the “Prompts” subsection in “Structure and markup” with clearer info on using prompts and prompt entities (always specify regular or elevated privileges).

Terminology update: flash disk → flash drive, in sync with TermWeb.

“Language” and “Terminology” updated with info about TermWeb that is now fully launched and available to all SUSE employees.

The style guide changed its structure to the three-column layout with clearly featured subsections.

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 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 terminology entry for subsystem.

Improved guidance regarding numbers and measurments.

Added guidance regarding XML formatting.

Improved guidance regarding commands.

Documented ID prefix for prefaces.

Added guidance regarding scaling of screenshots.

Added terminology entries for use case, business case.

Improved guidance regarding use of prompts.

Added guidance regarding list structure.

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 7.9, “Example of a figure”: <textobject/> must be within <mediaobject/>.

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

Improved clarity and fixed typos.

Brought Style Guide into better compliance with itself using the style checker tool.

Moved Section 6.9, “Headings” from Chapter 7, Structure and markup into Chapter 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.

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.

Restructured large parts of the style guide

Restructured terminology list, added more terminology

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 Chapter 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 Chapter 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 Chapter 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.

Added Section 9.4, “XInclude elements”.

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 7.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.