1. Introduction
1.1 What is DITA?
DITA (Darwin Information Typing Architecture) is an XML-based framework for creating, managing and publishing modular technical documentation. It is widely used by global organisations to ensure consistency, reusability and efficiency across their documentation.
Note: You would need to thoroughly study DITA and technical documentation through external resources to gain a proper understanding of the subject matter. Additionally, you must familiarise yourself with customer-specific requirements.
1.2 Key mechanisms of DITA
Key features include:
- Modularity: Content is organised into small, self-contained units called topics (e.g. concept, task or reference).
- Content-Formatting Separation: Content is tagged semantically and formatted only during publication.
- Conditional Processing: Content is included or excluded based on metadata, such as audience or product version.
- Maps organise topics into hierarchies and define document structure.
- Topics are self-contained units of content with specific types (e.g. tasks or concepts).
- Tags provide semantic meaning to content (e.g. User Interface terms or for links).
- Variables and Metadata control content reuse and conditional processing.
2. Guidelines for handling tags
You should be familiar with the in-line tags commonly found in DITA segments and know how to manage them effectively.
Note: This section requires prior knowledge of XML, tags and attributes.
2.1 Principles
Tags usually occur in pairs (opening and closing) and provide information on the content between them.
There are several cases where tag pairs can be grouped in one single "autoclosing tag":
- When the tag is used as a variable: its value will be automatically populated when content is published.
- When the content has been protected from translation and “locked” for translation.
- For internal links. In that case the tag will be replaced by the title of the content the link is pointing to.
Tags are often accompanied by attributes that provide information for the engines that will process the content. Attributes are not translated.
2.2 How to display tags in Smart Editor
Smart Editor offers three levels for displaying tags:
- Numbers only
- Metadata only
- Both (numbers and metadata)
Note: To change the tag display in Smart Editor, click on VIEW > Tag display and select one of the three options above.
Numbers only: Tags or tag pairs are represented by numbers with a blue background
Metadata only: The complete value of the tag is shown; this includes the element and the attributes
Both (numbers and metadata): The complete value of the tag is shown (this includes the element and the attributes), together with the tag numbers
Tip: Regardless of the selected tag display option, you can hover over tags to show its corresponding values:
2.3 Valuable features
To help you handle tags, Smart Editor provides two features:
- A preview window showing the content rendered in English. However, the preview feature is not always fully functional for XML formats.
- Several QA checks related to tags (e.g. mismatched tag order, extra tags, missing tags, etc.). Please note that QA checks can result in warnings (segment saving is allowed) or errors (segment saving is not allowed).
Tip: Further information on tag handling in Smart Editor can be found here, and the complete list of QA checks, including those related to tags, can be found here.
3. Main DITA in-line tags
Although DITA content includes many types of tag, only a few of them are found in to-be-translated segments. A full list of elements can be found here: DITA 1.3 list of elements, while the table below includes the in-line tags that can occur in segments for translation.
Note: Information on how to handle tags for customer content will be included in the job briefing and/or company briefing for the entity.
| In-line tags | Explanation |
| <alt>: Alternate text | It is always included in an <image> pair of tags. It provides an alternate text describing the image which will be displayed if image is missing, or read to hearing-impaired user. |
| <b>: Bold | Its content will be displayed in bold. Please refer to the job briefing and company briefing. |
| <cite>: Citation | Its content usually includes the title of a document. It should be present in the termbase. |
| <codeph>: Code Phrase | Its content is a snippet of code. It should be locked for translation and appear as a single tag. If it is ever unlocked for translation, please refer to the job briefing and/or reach out to the LanguageWire project manager via Messages. |
| <codeblock>: Code Block | Its content is a block of code. It should be locked for translation and appear as a single tag. If it is ever unlocked for translation, please refer to the job briefing and/or reach out to the LanguageWire project manager via Messages. |
| <i>: Italic | Its content will be displayed in italic. Please refer to the job briefing and company briefing. |
| <keyword>: Industry or customer term | Its content refers to industry or customer lingo. It should be present in the termbase and translated consistently. |
| <menucascade>: software menu cascade | Example: “File>Open”; It can contain a series of <uicontrol> only with no extra characters. The > character will be automatically inserted. |
| <ph>: Phrase or Placeholder |
It holds no semantic value. Depending on the attributes: • @conref, @conkeyref or @keyref, it holds a variable that will be populated when content is published. • @audience, @product or @otherprops, it introduces conditional content that will displayed or not in the output. |
| <q>: Quote | Its content will be displayed between “quotes”. Please refer to the job briefing and company briefing. |
| <systemoutput>: System Output | Its content represents a message provided by software. Its content should be translated according to the job briefing: from the termbase, free translation between (), etc. |
| <term>: Industry or customer term | Its content refers to industry or customer lingo. It should be present in the termbase. When autoclosing (i.e. not a pair of tags with content in between) it includes a @keyref attribute, it links to a glossary and holds the “term” as a variable which will be populated when content is published. |
| <tm>: Trademark | Its content should be a product or a brand to be translated according to the job briefing: usually from the termbase or “Do Not Translate”. |
| <uicontrol>: software string | Its content should be translated according to the job briefing and company briefing: from the termbase, free translation between (), etc. |
| <userinput>: User input |
Its content represents a string to be entered by the user. It should not be translated unless otherwise specified in the job briefing. |
| <wintitle>: software menu element | Its content should be translated according to job briefing: from the termbase, free translation between (), etc. |
| <xref>: Link | It can be a link to another section in the document or an external link on the Internet. If it is autoclosing (i.e. not a pair of tags with content in between), it will be automatically replaced by the title of the linked section. |
4. Common issues and troubleshooting
-
Tag Errors: A segment in Smart Editor cannot be saved due to a QA error related to tags (i.e. extra or missing tags, mismatched tag order, mismatched tag pair).
- Solution: Use the QA checks to locate the issue to be solved and amend the affected segments accordingly (e.g., by adding missing tags or updating the tag order so that it matches that of the source).
-
Variable handling: Variables are words or groups of words that are introduced when content is published. They can cause grammatical issues due to their dynamic nature.
- Solution: Please consult with the LanguageWire project manager via Messages if variable translations require adjustments.
-
Conditional Content Challenges: Conditional content creates inconsistencies or grammatical issues.
- Solution: Pay attention to spacing, gender and number agreements. Please consult with the LanguageWire project manager via Messages if you notice such a potential issue.