SUSE Documentation Style Guide #

Use http://www.example.com and http://www.example.org as example domains. Both domains were registered for use in documentation.

Use objects of the solar system: For the most important system, use sun. For other systems, use the names of planets such as earth or mars.

Use addresses from the class C subnet 192.168.255.0 for examples. That is, replace the final 0 by any integer between 0 and 255. To create examples using a larger setup, use addresses from the private network ranges. For more information, see http://en.wikipedia.org/wiki/Private_network.

Use addresses from the subnet 2001:0db8::/32 for examples. That is, after the 2001:0db8: prefix, add six four-digit numbers, each separated by a colon on both sides. Each of the hexadecimal digits may have a value between 0 and f. A valid example URL is 2001:0db8:0123:4567:89ab:cdef:1234:5678. For more information, see http://en.wikipedia.org/wiki/IPv6_subnetting_reference.

For example users, use free-software mascots, such as Tux (Linux Kernel), Wilber (The GIMP), Geeko (SUSE), Foxkeh (Firefox), Konqi (KDE), or Duke (Java). In prompts, use the lowercase version of these names.

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

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

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

Avoid using abbreviations, especially unusual ones. Avoid creating plurals of abbreviations, unless the abbreviation is an acronym or initialism.

Do not artificially limit your audience by excluding or offending members of it.

Avoid indicating gender in your documentation. If possible, use plural to allow use of “they” as the pronoun. Otherwise, use “he or she.”

SUSE supports the Inclusive Naming Initiative which aims to help avoid harmful language. When making language choices for documentation, review the initiative's Word List and the Evaluation Framework.

For more information about avoiding gender bias, refer to The Chicago Manual of Style, 5.43. For information about names of example items, see Section 3, “Names of example items”.

Use commas between all items in a series of three or more elements. For example, write “a, b, and c.” Use commas around phrases like for example and that is. Introductory phrases at the beginning of a sentence are normally followed by a comma. For example, “Before using YaST Online Update, configure a network connection.”

Do not use contractions, unless you are purposefully writing a casual document.

Use en dashes (–) between numbers in a range in tables and figures.

For punctuation, use em dashes (—). Do not surround em dashes with spaces. Use em dashes sparingly.

End sentences in a period. Avoid using exclamation marks. Restrict question marks to question and answer sections.

Under Linux, objects like directories, printers, or flash disks are all considered files. Therefore, the naming and markup conventions are the same for “drives” (for example, hard disks, CD-ROM drives), directories, or files.

The layout for file names and directory names is the same. See the following example:

Most Linux file systems are case-sensitive. Use capitals exactly as they appear in the file system. For more information on markup aspects, see Section 6.14, “References to other external resources” and Section 6.4.2, “File names”.

When it is necessary to refer to file extensions, such as in compound words like “PDF file”, always capitalize the extension.

When writing a descriptive section, use a noun-based heading title, for example, “Concepts of Software”. When writing a task-orientated section, use a verb in gerund, for example, “Installing Software”.

Keep headings short and simple. Do not use both an acronym and the expanded form in a heading. Make sure that headlines in a chapter follow the same pattern.

For advice on how to nest sections, refer to Section 6.15, “Outline levels and sectioning”.

For information about creating lists, see Section 6.12, “Lists”.

Write the integers zero through nine as words. Use numerals for all other numbers.

When the unit of a measurement is abbreviated, always use numerals for the number. In measurements, add a non-breaking space (   ) between the numeral and its corresponding unit abbreviation.

For more information, refer to The Chicago Manual of Style 9.6 and 9.16.

Do not use possessives of acronyms and trademarked terms. Avoid possessives of inanimate objects.

Add a hyphen after the prefix to prefixed words only if:

Avoid using semicolons to join sentences. You may use semicolons in place of commas in very complicated series.

Do not use slashes except when they are part of a standard technical term, such as TCP/IP or client/server.

Form clear and direct sentences with 20 words or less. Avoid complicated clauses. Make sure that the relationship between subject, verb, and object are clear. Avoid joining sentences with semicolons. Avoid ending sentences with prepositions.

Avoid using parentheses. Where they are necessary, move them to the end of the sentence. Never nest parentheses.

Always let the reader know the objective of an action before describing the action itself. As an example, write: “To restore world peace, click Shake hands.”

Use the simple present tense. Apply the simple present tense even to sentences with “if” or “when” clauses: “If this happens, go there.”

Prerequisites of an action should be expressed in the present tense as well: “Glibc is installed.” In some cases, no verb is necessary before the prerequisite of an action: “a 1 GHz processor or better.”

Maintain a professional tone. Do not use contractions, except in casual documents. Do not use humor. Be honest and avoid absolutes and exaggerations, but focus on positive aspects.

Use second person (“you”) to refer to the reader. Normally, the reader is the user or administrator who performs the actions described. Do not overuse “you.” It is often understood, especially in directions.

Where possible, use active voice. In active voice, the subject of the sentence performs the verb. For example, “The root user performs administrative tasks” is active voice. “Administrative tasks are performed by the root user” is passive voice.

Use passive voice if there is no emphasis on the object of the verb or if the performer of the action is unknown. “A Samba server must be configured in the network” is an example of proper use of passive voice. The emphasis is on the server, not on the person configuring it.

Most products referenced in the documentation are trademarked. Follow these rules when dealing with these terms:

For more information on markup aspects, see Section 6.17, “Products”.

When referring to labels of user interface items, do not include ending punctuation such as … or :. Whenever possible, refer to user interface items without identifying them as any special type of element. For example, use “click OK” rather than “click the OK button.” However, complex dialogs may require more specific wording.

When referring to UI labels, capitalize them exactly as in the UI itself. Software created at SUSE (such as YaST or Uyuni) should use sentence-style capitalization. If it does not, you can make aware the developers of that software. For more information about sentence-style capitalization, see Section 5.3.1, “Most titles: sentence-style capitalization” and the SUSE Product Brand guide.

For more information about markup for UI labels, see Section 6.20, “User interface items”.

Use quotations to quote from sources, such as books. In other cases, avoid using quotation marks. Do not use irony and do not use quotation marks to mark irony. In the case of computer input, computer output, and user interface elements, use more appropriate markup. See also Section 6.4, “Command line input and command line output” and Section 6.20, “User interface items”.

To create quotations, use the <quote/> element, as it is easier to localize than hardcoded quotation marks and always provides typographic quotes.

Punctuation directly following the quoted text should be included within the quotation marks, as illustrated in Example 4, “Quote”.

To make readers aware of potential problems and recent changes, or to give them tips, use an admonition element. Avoid using more than one admonition per page of PDF output.

Follow these rules when writing admonitions:

<warning>
 <title>Do not interrupt creation of file systems</title>
 <para>
  Creating a file system can take multiple hours.
  Interrupting this process will result in a corrupt file system and an
  unusable installation.
 </para>
 <para>
  Always wait until formatting has finished.
 </para>
</warning>

Warning: Do not interrupt creation of file systems

Creating a file system can take multiple hours. Interrupting this process will result in a corrupt file system and an unusable installation.

Always wait until formatting has finished.

When referring to an application, add a <phrase role="productname"/> element around it:

<phrase role="productname">LibreOffice</phrase> is an office suite.

This will not result in a visual change but disables hyphenation in browsers. This markup sidesteps hyphenation issues of CamelCased names.

Callouts allow annotating examples, such as configuration files or commands with many options. Add <co/> elements directly after the part of a screen that you want to annotate. Do not try to align them above the part of a screen to annotate. Do not use more than ten callouts per example.

See also Section 6.7, “Examples”.

<screen>color white/blue black/light-gray <co xml:id="co-color"/>
default 0 <co xml:id="co-default"/></screen>
<calloutlist>
 <callout arearefs="co-color">
  <para>
   Colors of the boot loader menu.
  </para>
 </callout>
 <callout arearefs="co-default">
  <para>
   Defines the preselected option.
  </para>
 </callout>
</calloutlist>

color white/blue black/light-gray 1
default 0 2

When dealing with user input and system output shorter than 30 characters, format it with an inline element, such as <command/> or <filename/>. In all other cases, close the current paragraph and enclose the user input and/or system output in a <screen/> element. See also Section 6.7, “Examples”.

When using <command/> elements standalone, that is outside of a <screen/>, do not use <prompt/> elements before or within them. For more information about <prompt/>, see Section 6.4.5, “Prompts”.

To start LibreOffice from the command line, use
<command>loffice</command>.

To start LibreOffice Writer from the command line, use
<command>loffice --writer</command>.

Find the log file <filename>configuration.xml</filename>
in the directory <filename>/etc/sysconfig</filename>.

To list the contents of a directory, execute
<command>ls <replaceable>DIRECTORY</replaceable></command>.

To create a comment, insert <literal>#</literal> characters.

<prompt>tux &gt; </prompt><command>ls</command>

<prompt>root # </prompt><command>yast</command>

<screen><prompt>tux &gt; </prompt><command>ls /</command>
bin   dev   lib         mnt     proc  sbin     suse  usr
boot  etc   lib64       mounts  root  selinux  sys   var
data  home  lost+found  opt     run   srv      tmp</screen>

To select another display manager, start the YaST system configuration editor
and change the value of <varname>DISPLAYMANAGER</varname>.

Use the <xref/> element (read: “cross ref”) when referring to an appendix, chapter, example, figure, part, preface, section, table, or question and answer set. The element referenced needs to have an xml:id attribute. Do not prefix or suffix cross references with text labels such as “appendix,” “chapter,” “table,” or “figure.” Such labels are generated automatically.

Do not create references to paragraphs (<para/>) or other elements that have no title. An exception to this rule is the element <step/> to which you may create references. If a reference to an element without a title is vital to the document, use the attribute xreflabel to assign a title.

Other types of references to resources are described in Section 6.14, “References to other external resources” and Section 6.8, “External links”. Create identifiers to reference from cross references using the rules under Section 6.11, “Identifiers”.

<sect2 xml:id="sec-cross-reference">
 <title>Cross references</title>
 <para>
  Use the <sgmltag class="emptytag">xref</sgmltag> element ...
 </para>
...
 <para>
  See <xref linkend="sec-cross-reference"/>.
 </para>
</sect2>

Where possible, indicate stress with language only. If that is not possible, use the <emphasis/> element to indicate stress.

Where added emphasis is needed, use the role="bold" attribute.

This will be displayed in <emphasis>italics</emphasis>. This
will be displayed in <emphasis role="bold">bold</emphasis>

Use examples to illustrate complex processes. The rules established in Section 6.9.1, “Graphics” also apply to examples.

Examples usually contain <screen/> elements. Additionally, there can be callouts and explanatory text.

Always give examples a title and an identifier.

For more information on screen environments, see Section 6.4.6, “Screens”. For more information on displaying computer input and output, see Section 6.4, “Command line input and command line output”. To annotate examples, use callouts. Callouts are described in Section 6.3, “Callouts”.

<example xml:id="ex-example">
 <title>Example of an example</title>
 <screen><prompt>tux &gt; </prompt><command>ps -xa</command>

5170 ?        S      0:00 kdeinit: khotkeys
5172 ?        S      0:02 kdeinit: kdesktop
5174 ?        S      0:04 kdeinit: kicker</screen>
</example>

Information that is relevant within SUSE documentation is often available from other Web sites already. In such cases, choose between linking to these sites or including their content in edited form. Adhere to the following guidelines when selecting sites to link to:

In some cases, product managers will request avoiding all or selected external links to avoid issues for customers impacted by restrictive firewalls.

Use the <link/> element to mark up URLs that can be opened with a Web browser, such as https://www.example.org/. Always add the correct protocol prefix (for example, https://), otherwise links will not work. Never use filename for a link, as that would both disable the link checker and make the link unclickable. Avoid entering a text label between <link/> start and end tags. Instead, use a self-closing tag:

<link xlink:href="https://www.example.org/"/>

Make URLs as short as possible before adding them to documentation. Many long URLs can be shortened by leaving away non-essential pieces, such as the _utm parameters used for marketing purposes. If a Web site provides a built-in URL shortener, use it.

Do not use third-party URL shorteners, such as bit.ly. Third-party URL shorteners have the following disadvantages:

Do not use <link/> to link to SUSE documentation outside of the current document set. Instead, use the appropriate entity for the book title. Always reference the book itself, as chapter names can change.

Where possible, collect links in a “For More Information” section at the end of the chapter. This helps readers focus on your documentation instead of leading them immediately to other resources.

To mark up multiple links, create an <itemizedlist/> around them. Do not use a list environment for a single link. If you need to present many links, group them by topic and create a separate list environment for each group. Provide a comprehensive title for each of the groups or an introductory sentence. For more information on creating lists, see Section 6.12.1, “Itemized lists”.

Where possible, provide translators with localized versions of links in the comments of the source file.

Other types of references to resources are described in Section 6.5, “Cross references” and Section 6.14, “References to other external resources”.

For figures within lists or procedures, use the <informalfigure/> element. In all other cases, use the <figure/> element. Always assign an xml:id attribute to <figure/> elements. Reference figures from the text by means of a cross reference. For more information, see Section 6.5, “Cross references”.

All referenced image files must have a lowercase alphanumeric file name. Provide an appropriate image width using the width attribute. Always add a <textobject role="description"/> as in Example 11, “Example of a figure” to provide an alternative text for the HTML output.

<figure xml:id="fig-picture">
 <title>An interesting picture</title>
 <mediaobject>
  <imageobject role="fo">
   <imagedata fileref="picture.eps" width="80%" format="EPS"/>
  </imageobject>
  <imageobject role="html">
   <imagedata fileref="picture.png" width="80%" format="PNG"/>
  </imageobject>
  <textobject role="description">
   <phrase>Cat chasing Geeko</phrase>
  </textobject>
 </mediaobject>
</figure>

An optional glossary contains terms and their definitions. Make sure that the glossary entries are appropriate to the intended audience. Define unfamiliar terms and special jargon.

Define infinitive forms of verbs and singular nouns. Use lowercase for the term unless it is a proper noun.

Use cross-references to link acronyms with their written out forms. Define the written out form. Use a See reference for the acronym form to link it to the defined written out form.

The markup for a glossary entry is shown in Example 12, “A typical example of a glossary”.

<glossary>
<title>Glossary</title>
 <glossentry>
  <glossterm xml:id="gt-extensible">Extensible Markup Language</glossterm>
  <glossdef>
   <para>
    A markup language that defines a set of rules for encoding documents in a
    format that is both human-readable and machine-readable.
   </para>
  </glossdef>
 </glossentry>
 <glossentry>
  <glossterm>XML</glossterm>
  <glossdef>
   <para>
    See also <xref linkend="gt-extensible"/>.
   </para>
  </glossdef>
 </glossentry>
</glossary>

Do not rework identifiers in existing documentation, instead apply these rules to newly created documentation only.

SUSE documentation uses the following types of lists (the respective XML elements are given in parentheses):

Follow these rules when creating or editing lists:

Never nest more than three lists within each other. Instead, restructure the information using a combination of lists and running texts.

To be able to reference untitled lists, use the xreflabel attribute. For more information, see Section 6.5, “Cross references”.

<para>
 The following operating systems are supported:
</para>
<itemizedlist>
 <listitem>
  <para>
   Linux, Kernel 2.4 and newer
  </para>
 </listitem>
 <listitem>
  <para>
   FreeBSD 7 and newer
  </para>
 </listitem>
</itemizedlist>

<para>
 Before installing, make sure of the following:
</para>
<orderedlist>
 <listitem>
  <para>
   The network connection of the computer is configured properly.
  </para>
 </listitem>
 <listitem>
  <para>
   The latest security updates are installed.
   If you are in doubt, run an online update.
  </para>
 </listitem>
</orderedlist>

<para>
 This book consists of several parts:
</para>
<variablelist>
 <varlistentry>
  <term>Installation</term>
  <listitem>
   <para>
    Learn about the installation and initial configuration of a Linux system.
   </para>
  </listitem>
 </varlistentry>
 <varlistentry>
  <term>System</term>
  <listitem>
   <para>
    Get a basic understanding of the system components.
   </para>
  </listitem>
 </varlistentry>
</variablelist>

Capitalize all keys as printed on a standard keyboard. Capitalize all letter keys. To refer to a capitalized character, use Shift–Z, for example. Introduce this convention by means of the “Typographical Conventions” section of the introduction.

To mark up key combinations, use <keycombo/> as a wrapper for multiple <keycap/> elements. Separators between <keycap/> elements are then created automatically.

If a key is listed in Table 8, “Elements related to <keycap/>”, use the function attribute with the appropriate value. When using the function attribute, make the tag self-closing—DocBook's language files will insert key names automatically. This simplifies both your work and the work of translators.

For more information on creating cross references, see Section 6.5, “Cross references”.

To create a screenshot, press <keycap>Print Screen</keycap>.

To save a file, press
<keycombo><keycap function="control"/><keycap>S</keycap></keycombo>.

To reference file names, use the <filename/> element. To reference e-mail addresses, use the <email/> element. In either case, do not include a protocol prefix, that is file:// or mailto:, respectively. See also Section 6.4.2, “File names”.

Reference man pages and info pages in this format:

In a situation where the category of the page is needed, append the category in parentheses. Use, for example “(man 9 command)”.

To learn more about subcommands, see the man page of
<command>command</command>.

Insert references to external (non-SUSE) physical books in the format “Title by Author (ISBN #00000000).” Inclusion of the ISBN is optional. Place the title in a <citetitle/> element. For example:

<citetitle>Lorem Ipsum</citetitle> by Dolores S. Amet
(ISBN 0-246-52044-7) is a useful guide.

As an author, where possible, provide language-specific references to translators in XML comments (see also Section 7.2, “XML comments”). As a translator, look for corresponding language-specific resources where none have been provided. For URLs, provide only the language-specific version of a site. Use the English version as a fallback. For books, provide the title of the translated version along with the original title if such a translation exists.

Other types of references to resources are described in Section 6.5, “Cross references” and Section 6.8, “External links”.

Create sections using the <sect1/>, <sect2/>, and <sect3/> elements. Avoid outlines that require <sect4/> and <sect5/> elements. Instead, create a flatter structure in which more elements are visible at a glance.

Provide at least one paragraph of introductory information directly within each section.

Do not create lone subsections. A lone subsection is a section that is the only subsection of its parent section.

For more information on writing headlines, see Section 5.9, “Headings”.

Use procedures to describe sequential tasks. A procedure consists of the following elements and attributes:

To link alternative actions inside the same substep element, use “or.” Apply a performance=optional attribute to optional steps.

Steps may contain a link to an explanatory subsection providing further details on the step.

<procedure xml:id="pro-procedure">
 <title>Example of a procedure</title>
 <para>
  To add a new user to the system, perform the following steps:
 </para>
 <step>
  <para>
   In the <phrase role="productname">YaST</phrase> window,
   click <guimenu>User and group management</guimenu>.
  </para>
 </step>
 <step>
  <para>
   To open the <guimenu>Add a new user</guimenu> dialog, click
   <guimenu>Add</guimenu>.
  </para>
 </step>
 <step>
  <para>
   Type in the user name and click <guimenu>Create</guimenu>.
  </para>
 </step>
</procedure>

Always use the preferred product name instead of, for example, an acronym. When referring to a product, add a <phrase role="productname"/> element around it. This will not result in a visual change but disables hyphenation:

<phrase role="productname">LibreOffice</phrase> is an office suite.

Use questions-and-answers sections to present information about troubleshooting or commonly asked questions about a product. Never use questions-and-answers sections to explain trivia, such as how a product got its name. Keep your audience in mind. See also Section 1, “Audience”.

Questions must always end in a ?. Where explanations longer than three paragraphs are necessary for an answer, add a cross reference to an explanation outside of the questions-and-answers section. See also Section 6.5, “Cross references”.

When a questions-and-answers section contains over 10 questions and there are clear topical divisions, add <qandadiv/> elements to further structure the section.

<qandaset>
 <title>Example of a questions-and-answers section</title>
 <qandaentry>
  <question>
   <para>
    How can I check if the product was correctly installed?
   </para>
  </question>
  <answer>
   <para>
    Open the log file.
    Look for entries starting with <literal>Failed</literal>.
   </para>
  </answer>
 </qandaentry>
 <qandaentry>
  <question>
   <para>
    Why does the error <literal>Not enough disk space</literal> occur
    during installation?
   </para>
  </question>
  <answer>
   <para>
    There are less than 4 GB of space available on the selected partition.
   </para>
  </answer>
 </qandaentry>
</qandaset>

Use tables to present many similar facts. Tables are easy to scan and compare. Always keep tables simple enough to not require long explanations even for readers unfamiliar with the topic.

A table always has a title and should have an xml:id attribute.

Value and description pairs are better handled by means of a descriptive list.

<informaltable>
 <tgroup cols="2">
  <thead>
   <row>
    <entry>File System</entry>
    <entry>Maximum File Size</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>Ext2 (1 kB block size)</entry>
    <entry>16 GB</entry>
   </row>
   <row>
    <entry>Ext2 (2 kB block size)</entry>
    <entry>256 GB</entry>
   </row>
  </tbody>
 </tgroup>
</informaltable>

To mark up single user interface items, use <guimenu/>. To mark up nested menu structures, use <menuchoice/> as a wrapper for multiple <guimenu/> elements. Separators between <guimenu/> elements are then created automatically.

For more information on language aspects, see Section 5.20, “User interface items”.

To open a file, click <guimenu>Open</guimenu>.

To save a file, use
<menuchoice><guimenu>File</guimenu><guimenu>Save</guimenu></menuchoice>.

Use remarks for editorial comments. Remarks can be placed within, before, or after a para but must always be within a section element. When creating output, remarks can be made visible in the output and thus help within the editorial process. When creating the final output, deactivate remarks.

Start remarks with your user name and the current date, then add a colon (:) and finally your actual remark. To comment on someone else's remark, add a new remark directly below it. Delete remarks when the corresponding issue is resolved.

<remark>tux (2013-10-13): could not find the option for foo</remark>
<remark>geeko (2013-11-02): see /usr/share/doc/foo.html</remark>

You can add a role attribute with one of the following values to show the type of the remark:

XML comments can be used for temporarily disabling portions of text. Another use of XML comments is to create more permanent internal comments or to mark up changes made for layout reasons. XML comments are never visible in a publication.

<!-- This is an XML comment. -->

For information about formatting XML comments, see Section 8, “Formatting XML”.

Entities are used to expand text. There are several situations in which they can be used:

When an entity is defined, it can be used in many places. Entities increase consistency, as they only need to be defined once and will automatically be expanded everywhere within the document.

<!ENTITY % entities SYSTEM "entity-decl.ent">
%entities;

<!ENTITY1 server2 "sun3">
<!ENTITY domain  "example.org">
<!ENTITY host    "&server;.&domain;4">
<!ENTITY hosttag "<uri xmlns='http://docbook.org/ns/docbook'>&host;</uri>5">

XInclude elements are used to create modular source files that are easier to work with and can be re-used. When editing a book, create a new source file for every chapter. Later, create a new GeekoDoc file that can serve as the central point. In this file, use XInclude elements to reference all chapters in the correct order:

<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="gfdl.xml"/>

XInclude elements allow adding common sections to multiple books or articles without having to maintain the text in multiple places. Common sections include licenses and information on typographical conventions. XIncludes also simplify co-editing documentation with others in a version control system as they reduce the chance of merge conflicts.

By default, files referenced via XIncludes must be well-formed XML files that are also valid GeekoDoc fragments. This means that they must have a single top-level element and must not contain elements that are not allowed in GeekoDoc. Files that are supposed to be referenced multiple times from within the same set, book, or article must not contain any xml:id attributes.

XIncludes also allow embedding plaintext files, for example, as the content in <screen/> elements. To embed a plaintext file, add the attribute parse="text" to the <xi:include/> element.