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