Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
documentation.suse.com / SUSE Documentation Style Guide / Working with Smart Docs
Applies to 2024-10

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 nameDescriptionTranslation
<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 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:

  • 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), you may 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>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>
Example 12.2: Revision history example (output)
 
Revision History
2024-11-13 

Updated chapter on “foo bar”, removed section on “foo bar 1”

2024-09-21 

Updated for the initial release of SUSE Linux Enterprise Server 15 SP6