Applies to 2024-05

12 Working with Smart Docs #

Smart Docs represent a modular approach to documentation whose goal is producing sets of adaptable, solution-based, easy-to-find and reusable documents.

Rather than covering a complete technology or a set of problems, each Smart Docs article serves one distinct purpose. Each article stands for itself, including requirements, context, instructions, troubleshooting and FAQs.

Smart Docs consist of topics—smaller information units that can be reused in different contexts. Four different topic types are provided:

Task topics instruct the user how to perform certain tasks.
Concept topics explain underlying concepts to the users.
Reference topics inform the user about basic facts (settings, options, parameters, etc.).
Glue topics help navigate complex topics and provide links to related information (combine texts or structures that do not fit into any other category). Typical glue topics include “For more information” and “What's next” sections. Use glue topics to provide an additional layer of navigation for your article.

Articles are built by bundling these topics into assembly files—organizational units to structure the topics to create a coherent and meaningful document.

To create a Smart Docs project, use the templates for the assembly and its topical components that are provided in the doc-modular repository.

12.1 Using ITS tags with assemblies #

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.

Element name	Description	Translation
<meta name="bugtracker" its:translate="no">	SUSE-specific info needed by the doc-manager tool and DAPS to process and build SUSE user documentation.	No
<phrase role="url">https://bugzilla.suse.com/enter_bug.cgi</phrase>	SUSE-specific info needed by the doc-manager tool and DAPS to process and build SUSE user documentation.	No
<phrase role="component">Non-product-specific documentation</phrase>	SUSE-specific info needed by the doc-manager tool and DAPS to process and build SUSE user documentation.	No
<phrase role="product">Smart Docs</phrase>	SUSE-specific info needed by the doc-manager tool and DAPS to process and build SUSE user documentation.	No
<phrase role="assignee">assignee@suse.com</phrase>	SUSE-specific info needed by the doc-manager tool and DAPS to process and build SUSE user documentation.	No
<meta name="translation" its:translate="no"/>	SUSE-specific info needed by the doc-manager tool and DAPS to process and build SUSE user documentation.	No
<phrase role="trans">yes</phrase>	SUSE-specific info needed by the doc-manager tool and DAPS to process and build SUSE user documentation.	No
<phrase role="language">de-de,cs-cz</phrase>	SUSE-specific info needed by the doc-manager tool and DAPS to process and build SUSE user documentation.	No
<meta name="architecture" content="x86;power" its:translate="no"/>	SUSE-specific info needed by the doc-manager tool and DAPS to process and build SUSE user documentation.	No
<meta name="productname" its:translate="no"/>	The formal name of a product	No
<productname version="15-SP5">SLES</productname>	A number assigned to a product	No
<meta name="title" its:translate="yes"> short title for SEO and social media, max. 55 chars</meta>	SEO-specific info. Adhere to the length limitations.	Yes Stick to the length limitations, min. 29 chars and max. 55 chars
<meta name="description" its:translate="yes"> short description, max. 150 chars</meta>	SEO-specific info. Adhere to the length limitations.	Yes Stick to the length limitations, max. 150 chars
<meta name="social-descr" its:translate="yes"> ultrashort description for social media, max. 55 chars</meta>	SEO-specific info. Adhere to the length limitations.	Yes Stick to the length limitations, max. 55 chars
Doc Manager tags: <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>	`<info>`: Wrapper to contain bibliographic information about the content and other meta info. `<dm:PLACEHOLDER>`: SUSE-specific info needed by the doc-manager tool and DAPS to process and build SUSE user documentation.	No
Resources: <resource xml:id="_glue-example" href="../glues/glue.xml"> <description>Glue example</description> </resource>	SUSE-specific info needed by the doc-manager tool and DAPS to process and build SUSE user documentation.	`<resource>`No `<description>`Yes
Merge: <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>		`<title>`and `<subtitle>`Yes, with length limitations (see above) `<revhistory>`No `<module>`No `<title>`Yes

12.2 Revision history #

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 meta data. 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:

List revision entries in descending order by date. The latest entry must always come first.
Describe only significant changes that you performed.
If you have several changes of the same type (addition, change, removal), group them under a dedicated <itemizedlist/>.
Do not add links or references with xref of any kind. If you want to mention a specific issue, use the abbreviations from https://en.opensuse.org/openSUSE:Packaging_Patches_guidelines#Current_set_of_abbreviations and wrap it inside the tag uri.

Example 12.1: Revision history example (source) #

<revhistory xml:id="rh-USE-ROOTID">  
  <revision><date>2024-11-13</date>
    <revdescription>  
      <itemizedlist>
        <listitem><para>Added sections:</para>
          <itemizedlist>
            <listitem><para>New section on <quote>foo</quote> to resolve issue <uri>bsc#12345</uri></para></listitem>
            <listitem><para>New section on <quote>foo bar</quote></para></listitem>
          </itemizedlist>
        </listitem>
        <listitem><para>Removed sections:</para>
          <itemizedlist>
            <listitem><para>Removed section on <quote>foo1</quote> to resolve issue <uri>bsc#12346</uri></para></listitem>
            <listitem><para>Removed section on <quote>foo1 bar</quote></para></listitem>
          </itemizedlist>
        </listitem>
        <listitem><para>Changed sections:</para>
          <itemizedlist>
            <listitem><para>Changed section on <quote>foo2</quote> to resolve issue <uri>bsc#12347</uri></para></listitem>
            <listitem><para>Changed section on <quote>foo2 bar</quote></para></listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>
    </revdescription>
  </revision>
</revhistory>

Example 12.2: Revision history example (output) #

Revision History
	2024-11-13
Added sections: New section on “foo” to resolve issue `bsc#12345` New section on “foo bar” Removed sections: Removed section on “foo1” to resolve issue `bsc#12346` Removed section on “foo1 bar” Changed sections: Changed section on “foo2” to resolve issue `bsc#12347` Changed section on “foo2 bar”