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

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:

The most important thing to do with your Web copy is to help users get answers to their questions as soon as possible. To achieve this, we recommend the modular approach of topic-based authoring where documentation is created and maintained in chunks, subsequently referred to as topics.

Topics have the sole purpose of supporting users in their tasks. Each topic focuses on one specific subject and has one distinct purpose. We write topics in a way that they can stand alone as well as in context with other topics. They should also be reusable in different contexts.

Recommendations:

SEO, or Search Engine Optimization, is the strategy to attract organic (unpaid) traffic that originates from online search and refers to visitors landing on the Web site. When it comes to SEO, content is key. Here are some insights to help you create and design the content that will rank high in search engines.

Accessible technical documentation is essential because it ensures information is available to all users regardless of disabilities or impairments. Many users rely on assistive technologies such as screen readers and alternative input devices to navigate Web pages. Additionally, accessible documentation supports compliance with legal requirements and makes more online resources usable for everyone. Here are some guidelines on how to make content more accessible:

Remember that every document is a potential candidate for localization (translation). Make sure the document’s original English content is correct and clear. Simplicity, clarity and direct prose are essential.

Recommendations:

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, check the initiative's Evaluation Framework and its “Word lists.”

The SUSE official terminology database, TermWeb, also contains inclusive naming recommendations.

For more information about avoiding gender bias, see The Chicago Manual of Style, 5.43. For information about names of example items, see Chapter 4, Names of example items.

Capitalize the first word after a colon only if it is a proper noun or the start of a complete sentence. For example: “Error message: The system could not connect to the server.” But: “Server roles: file server, Web server and database server.”

Use commas to separate elements in a series of three or more elements, but do not put a comma before the conjunction in most simple series. For example, “Find basic information about how to register your system, modules and extensions.” 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 (such as “don't”), 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 drives 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 about markup aspects, see Section 8.18, “References to other external resources” and Section 8.3.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 8.14, “Outline levels and sectioning”.

Generally, hyphens are used as joiners for two or more words that form a single concept and function together as a compound modifier before the noun. If the noun comes first, the hyphen is not added. For example, “the list in the upper-left corner” but “place the list in the corner in the upper left.”

There are technical guidelines to help you choose whether to use or not to use a hyphen.

Add the hyphen when:

Do not use the hyphen when:

Many combinations that are hyphenated before a noun are not hyphenated when they occur after a noun. For example: “This is the up-to-date version” and “The calendar is up to date.”

For information about creating lists, see Section 8.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. Use the % sign when paired with a number, with no space.

For more information, see 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 you foresee misunderstandings. For example, there is a difference in meaning between “recreate” and “re-create.”

For more information about using hyphens, see Section 7.11, “Hyphens”.

Use quotations to quote from sources, such as books. In all other cases, do not use quotation marks:

The period and the comma always go within the quotation marks, as illustrated in Example 7.1, “Quote”. The dash, the semicolon, the colon, the question mark and the exclamation mark go within the quotation marks when they apply to the quoted matter only. They go outside when they apply to the whole sentence.

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

Form clear and direct sentences with 25 words or less. Avoid complicated clauses. Make sure that the relationship between subject, verb, and object is 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 save the settings, click OK.”

Do not use slashes except when they are part of a standard technical term, such as TCP/IP or client/server. Do not add spaces on either side of a forward slash.

Use the simple present tense. Apply the simple present tense even to sentences with “if” or “when” clauses and to prerequisites of an action. For example, “If this happens, go there.” or “Glibc is installed.”

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 the second person (“you”) to refer to the reader. Normally, the reader is the user or administrator who performs the actions described. For example, “To install all officially released patches that apply to your system, run zypper patch.” Do not overuse “you” and “your.” It is often implied who you are addressing in the instructions. For example, instead of “Install package on your system,” just say “Install package on the system.”

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

When giving a recommendation, start with “We recommend.” Do not use passive phrasings like “It is recommended.”

To refer to other parts of the document, start with “For more information (about), see.”

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

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 7.3.1, “Most titles: sentence-style capitalization” and the SUSE Product Brand guide.

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

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

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.

Callouts allow annotating examples, such as configuration files or commands with many options. Add callout elements directly after the part of a verbatim block 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 8.6, “Examples”.

[source]
----
color white/blue black/light-gray <1>
default 0 <2>
----
<1> Colors of the boot loader menu.
<1> Defines the preselected option.

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

When dealing with user input and system output shorter than 30 characters, enclose it with single backticks (`). In all other cases, close the current paragraph and enclose the user input and/or system output in a verbatim block. See also Section 8.6, “Examples”.

When using a stand-alone command elements outside of a verbatim block, do not use prompt elements before or within them. For more information about prompts, see Section 8.3.3, “Prompts”.

To start LibreOffice from the command line, use
`loffice`.

To start LibreOffice Writer from the command line, use
`loffice --writer`.

Find the log file `configuration.xml`
in the directory `/etc/sysconfig`.

8.3.3 Prompts #

 

When documenting commands entered into Bash with a verbatim block, always prefix them with a prompt marked up this way:

> ls

To avoid making prompts longer than necessary, do not include paths, user or host names, unless this is vital to understanding. The first restricted user must always be named tux. For more information about names of restricted users, see Chapter 4, Names of example items.

Whenever you provide commands in a verbatim block, make it clear if the user needs regular or elevated privileges. Avoid using root prompts in your documentation by using the sudo command where applicable. If you do need a root prompt, always mark it up as follows:

# yast

When documenting prompts other than the one of Bash, use a custom prompt that is as generic as possible.

For consistency, it is helpful to create entities (attributes) for the prompts used in your documentation. Doc Kit repository contains entities for user, root and sudo prompts. For more information, see Section 9.1, “Entities”.

Tip

Verbatim blocks normally do not expand attributes with their values. To use attributes for prompts in a verbatim block, add subs="+attributes" in its header:

[source,subs="+attributes"]
----
{prompt_root}zypper upgrade
----

To select another display manager, start the YaST system configuration editor
and change the value of `DISPLAYMANAGER`.

Use double angled brackets <<ID>> when referring to an appendix, chapter, example, figure, part, preface, section, table or question and answer set. The element referenced needs to have an identifier (ID). Create identifiers to reference from cross-references using the rules under Section 8.11, “Identifiers”. Note that a cross-reference only works when it links to documentation within the same set, for example, the same book or set of books.

Other types of references to resources are described in Section 8.18, “References to other external resources” and Section 8.7, “External links”.

[#sec-cross-reference,reftext=Custom cross reference]
=== Cross-references
Use double angled brackets for xrefs ...
See <<sec-cross-reference>>.

Keep in mind the following cases where listing cross-references is discouraged and must be avoided:

Do not prefix or suffix cross-references with text labels such as “appendix,” “chapter,” “table,” or “figure.” Such labels are generated automatically.

Where possible, indicate stress with language only. If that is not possible, surround the phrase with underscores (_phrase_) to indicate stress.

Where added emphasis is needed, enclose the phrase in a single pair of asterisks (*phrase*). To emphasize characters within a word, use a pair of double asterisks (char**act**ers).

 This will be displayed in _italics_.
This will be displayed in *bold*.

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

Examples usually contain source code blocks. Additionally, there can be callouts and explanatory text.

Always give examples a title and an identifier.

For more information about screen environments, see Section 8.3.4, “Verbatim blocks”. For more information about displaying computer input and output, see Section 8.3, “Command-line input and command-line output”. To annotate examples, use callouts. Callouts are described in Section 8.2, “Callouts”.

[#ex-example]
.Example of an example
====
[source]
----
tux > ps -xa

5170 ?        S      0:00 kdeinit: khotkeys
5172 ?        S      0:02 kdeinit: kdesktop
5174 ?        S      0:04 kdeinit: kicker
----
====

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 certain cases, product managers request avoiding all or selected external links to avoid issues for customers impacted by restrictive firewall rules.

Common URL schemes are automatically detected from the text and converted into links. To disable this conversion, use a single backlash (\) in front of the link (\https://example.org). To use a custom link title, use a URL macro:

Ask questions in the https://example.com[An example title]

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

For consistency, do not use the article in front of the name of the referenced book or chapter. For example, “The general concept of Podman is described in Containers and Podman.”

Where possible, collect links in a “More information” section at the end of the chapter. This helps readers focus on your documentation instead of leading them immediately to other resources. This is described in Section 5.1, “Books”.

To mark up multiple links, insert them into an unordered list. 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 about creating lists, see Section 8.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 8.4, “Cross-references” and Section 8.18, “References to other external resources”.

The SUSE documentation is hosted under documentation.suse.com. This is the URL that must be provided in all documents. The abbreviated URLs such as doc.suse.com and docs.suse.com also work but must be avoided for SEO reasons.

Make sure to use complete URLs instead of entities for an easy copy and paste.

Most links in our documentation that goes to documentation.suse.com refer to a specific product and release. However, sometimes it makes sense to not include the SP or even the major release. These are so-called SP-independent links.

The following reasons give you an idea when to use them:

Make sure to follow this syntax:

documentation.suse.com/<PRODUCT>[/<MAJOR_RELEASE>]/<DEEP_LINK>

The placeholders mean the following:

Make sure you use html and not single-html. This is needed for SEO reasons.

For example, the link https://documentation.suse.com/sle-ha/15-SP3/html/SLE-HA-all/article-installation.html#sec-ha-inst-quick-req/ points to the “System requirements” for SUSE Linux Enterprise Server High Availability Extension. To turn this link into an SP-independent link, you need to identify the different components first:

With the above parts, the redirection rules on our server allow expressing SP-independent links in several ways:

Note

If IDs have been changed between releases or SPs, this is what happens:

• If the hash part (everything after #) is not found, the browser will jump to the beginning of the file.

• If the file cannot be found (in our example, article-installation.html), the server will respond with a 404 error (file not found).

Use the image macro to insert an image. Always supply an identifier, title, appropriate width and alternative text to the image.

All referenced image files must have a lowercase alphanumeric file name. When specifying figure names, follow the naming conventions at https://github.com/SUSE/doc-modular/blob/main/templates/README.md.

.An interesting picture
[#fig-picture]
image::sunset.jpg[Cat chasing Geeko,200]

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. Do not start the definition with the term itself. Use lowercase for the term unless it is a proper noun.

Tip

To keep definitions consistent, check SUSE's official terminology database called TermWeb (https://suse.termweb.eu/search/terms). It contains company-specific terminology in English and all our supported languages. When defining a term, consult TermWeb first to ensure you are using the approved wording and preferred spelling.

You can include a glossary in an article, book and book part by setting the glossary style on a section.

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

[glossary]
== Glossary

[glossary]
AsciiDoc:: a lightweight markup language used to write structured documents in
  plain text.
DocBook:: an XML-based markup language designed for writing structured technical
  documentation.

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

SUSE documentation uses the following types of lists:

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, insert a label in the cross reference. For more information, see Section 8.4, “Cross-references”.

The following operating systems are supported:
* Linux, Kernel 2.4 and newer
* FreeBSD 7 and newer

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

This book consists of several parts:
  
Installation:: Learn about the installation and initial configuration of a Linux system.
System:: Get a basic understanding of the system components.

To enter keys and their combinations in the text, use the keyboard macro: kbd:[key] Capitalize all keys as printed on a standard keyboard. Capitalize all letter keys.

To mark up key combinations, enter multiple keys concatenated with +, such as kbd:[key+key+key+...].

Tip

If the last key is a backslash (\), it must be followed by a space. Otherwise the processor will not recognize the macro. If one of the keys is a closing square bracket (]), it must be preceded by a backslash. Without the backslash escape, the macro will end prematurely.

To create a screenshot, press kbd:[Print Screen].

To save a file, press kbd:[Ctrl+S]

Create sections by inserting = characters in front of their titles. The number of = characters determines the depth of the section in the document structure. Do not go deeper than section level 3. Instead, create a flatter structure in which more elements are visible at a glance.

= Document Title (Level 0)

== Level 1 Section Title

=== Level 2 Section Title

==== Level 3 Section Title

== Another Level 1 Section Title

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 about writing headlines, see Section 7.10, “Headings”.

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

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

[#pro-procedure]
.Example of a procedure

To add a new user to the system, perform the following steps:
. In the YaST window, click btn:[User and group management].
. To open the btn:[Add a new user] dialog, click btn:[Add].
. Type in the user name and click btn:[Create].

Profiling is convenient for the creation of consistent documentation across different products or product lines. This is especially beneficial when similar products share a considerable amount of features, with only a few differences. Instead of maintaining separate documentation for each product, you can share most of the source code and only vary text snippets where necessary. When profiling, you can mark specific elements as conditional and specify which conditions apply to the output when processing the files to generate output. The style sheets will then include or exclude the marked text, according to the conditions.

Profiling allows you to keep both common and product-specific content in one file and select at production time which information to include in the output.

If you need to use profiling in your writing, adhere to the following guidelines:

[...]
ifeval::["{prof-os}" == "sles"]
Note that the official update repository is only available after registering
your SLES installation.
endif::[]

MAIN="MAIN.SLEDS.xml"
ROOTID=book-administration
    
## Profiling
PROFOS="sles"
...

MAIN=book.adoc
# Profiling
PROFOS="sles"
...

Use question and answer sections to present information about troubleshooting or commonly asked questions about a product. Never use question and answer sections to explain trivia, such as how a product got its name. Keep your audience in mind. See also Chapter 2, Writing technical documentation.

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 question and answer section. See also Section 8.4, “Cross-references”.

[qanda]
.Example of a question and answer section
How can I check if the product was correctly installed?::
Open the log file.
Look for entries starting with `Failed`.

Why does the error `N` occur during installation?::
There are less than 4 GB of space available on the selected partition.

To reference file names, use a monospaced `filename` without the file:// prefix. To reference e-mail addresses, use the clickable mailto:john@example.com[] macro or unclickable monospaced `john@example.com`. See also Section 8.3.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. For example, use “(`man 9 command`)”.

To learn more about subcommands, see the man page of
`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 an italics snippet. For example:

_Lorem Ipsum<_ 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 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 8.4, “Cross-references” and Section 8.7, “External links”.

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

Typical use cases of tables include:

As there are use cases for tables, there are cases when not to use tables:

Some general style tips for tables:

.A table with a title
|===
|File System |Maximum File Size

|Ext2 (1 kB block size)
|16 GB

|Ext2 (2 kB block size)
|entry
|===

To mark up buttons when describing the user interface, use the button macro.

Press the btn:[OK] button to confirm your choice.

To explain how to select a menu item, use the menu macro.

Save the file by selecting menu:File[Save].
Select menu:View[Zoom > Reset] to reset the zoom level to the default setting.

Entities (or attributes) 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.

include::generic-attributes.adoc[]

:product-sp:1 12
:product-ga:  15
:productnumber-regurl:    {product-ga;.}{product-sp}3

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

[appendix]
include::common_license_gfdl1.2.adoc[]

Include 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. Includes also simplify co-editing documentation with others in a version control system as they reduce the chance of merge conflicts.

Assembly files use ITS tags and attributes which flag whether the content of the tag should be translated or not. In the following example, the ITS attribute indicates that the content of the tag should not be translated:

<meta name="maintainer" content="Smart Doc author" its:translate="no"/>

If the its:translate attribute is set to yes, translation is needed.

<meta name="bugtracker" its:translate="no">

<phrase role="url">https://bugzilla.suse.com/enter_bug.cgi</phrase>

<phrase role="component">Non-product-specific documentation</phrase>

<phrase role="product">Smart Docs</phrase>

<phrase role="assignee">assignee@suse.com</phrase>

<meta name="translation" its:translate="no"/>

<phrase role="trans">yes</phrase>

<phrase role="language">de-de,cs-cz</phrase>

<meta name="architecture" content="x86;power"
its:translate="no"/>

<meta name="productname" its:translate="no"/>

<productname version="15-SP5">SUSE Linux Enterprise Server</productname>

<meta name="title" its:translate="yes">
short title for SEO and social media, max. 55 chars</meta>

<meta name="description" its:translate="yes">
short description, max. 150 chars</meta>

<meta name="social-descr" its:translate="yes">
ultrashort description for social media, max. 55 chars</meta>

<dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
  <dm:bugtracker>
    <dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url>
    <dm:component>Smart Docs</dm:component>
    <dm:product>Documentation</dm:product>
    <dm:assignee>maintainer@suse.com</dm:assignee>
  </dm:bugtracker>
  <dm:editurl>https://github.com/SUSE/doc-modular/tree/</dm:editurl>
  <dm:translation>no</dm:translation>
</dm:docmanager>

<resource xml:id="_glue-example" href="../glues/glue.xml">
  <description>Glue example</description>
</resource>

<merge>
  <title>Your title, limit to 55 characters, if possible</title>
  <subtitle>Subtitle if necessary</subtitle>
  <revhistory xml:id="rh-USE-ROOTID">
    <revision>
      <date>2024-11-11</date>
      <revdescription>
        <para>
          Describe the purpose of this revision
        </para>
      </revdescription>
    </revision>
    <revision>
      <date>2024-10-10</date>
      <revdescription>
        <para>
         Describe the purpose of this revision
        </para>
      </revdescription>
    </revision>
  </revhistory>
  <module resourceref="_concept-example" renderas="section"/>
</merge>
<title>You are a very special concept now!</title>

A revision history lists all the high-level changes about the document itself. It gives the reader an overview of important changes made over time.

Update revision history regularly, mentioning most important changes to your document when you amend or rework it. The data you enter as revision history is used as metadata. The “Revision history” text is available as a link before the abstract and opens up in its individual page. Keep in mind the following rules:

<revhistory xml:id="rh-USE-ROOTID">  
  <revision><date>YYYY-MM-DD</date>
    <revdescription>  
      <para>Updated CONTENT, extended CONTENT, removed CONTENT</para>
    </revdescription>
  </revision>
  <revision><date>YYYY-MM-DD</date>
    <revdescription>  
      <para>Updated for the initial release of <phrase role="productname">SUSE Linux Enterprise Server</phrase> 
      <phrase role="productnumber">15 SP6</phrase></para>
    </revdescription>
  </revision>
</revhistory>