[DITA Loc Wire series] Imagine the web without hyperlinks. It just wouldn’t be. Hyperlinks enable us to make our way through the hundreds of billions of web pages. When web pages are deleted, moved, or updated, visitors end up in a dead-end with a 404 error message. Links need to be maintained up to date, and DITA gives you the framework to make it easier.
Hyperlinks are often treated as static text
We used to write some years ago:
Please refer to Microsoft Teams documentation to learn how to configure a guest access.
Now readers expect a direct link to the content:
Please refer to: Manage guest access in Microsoft Teams.
Here’s how it looks in DITA:
<p>Please refer to: <xref format="html" href="https://docs.microsoft.com/en-us/MicrosoftTeams/guest-access" scope="external"> Manage guest access in Microsoft Teams</xref>.</p>
In a technical document, you can find links to:
- The company website,
- Partner websites,
- Standard organizations,
- A plugin or app download page.
The same link might be inserted multiple times in different topics.
The web page URLs get updated by collaborators throughout the organisation and the technical writer is seldom notified. While content publishers want their users to have a good experience and get directly to the information they are after, they frequently land on such a page or a #404 page instead. These negative experiences show that the content is neglected and deteriorate the trust of the user.
What happens when it comes to localization?
Let’s suppose you have two topics, each phrased differently:
Topic A:
Please refer to Manage guest access in Microsoft Teams.
Topic B:
To configure your external project members, see Manage guest access in Microsoft Teams.
They will render the following translation into French:
(A) Veuillez-vous reporter à Gérer l’accès des invités dans Microsoft Teams.
(B) Pour configurer les membres externes pour votre projet, voir: Gérer les accès d’invités dans Microsoft Teams.
This generates three types of issues:
- The wording of the two anchor texts is different
- When you land on the page, the header might also be different. Here: Gérer l’accès invité dans Microsoft Teams.
- The updated URL might not point to the topic in the right language, and you are directed to the English page instead.
You can avoid these issues by writing instructions in the style guide. Make sure you take the time and effort to perform an in-depth QA after each translation. Or you can rely on DITA to avoid faulty links.
How to leverage DITA to maintain and localize external links
We recommend externalizing all the links in a reference file or set of files.
<?xml version=”1.0″ encoding=”UTF-8″?>
<!DOCTYPE topic PUBLIC “-//OASIS//DTD DITA Topic//EN” “topic.dtd”>
<topic id=”hyperlinks” xml:lang=”en-US”>
<title>hyperlinks</title>
<body>
<section>
<xref id=”manage_guest_access_Teams” format=”html”
href=”https://docs.microsoft.com/en-us/microsoftteams/manage-guests” scope=”external”>Manage guest access in Microsoft Teams</xref>
</section>
</body>
</topic>
In the topics, you just insert the links by writing the following:
<p>Please refer to <xref conkeyref=”hyperlinks/manage_guest_access_Teams”/>.</p>
OR
<p>To configure your external project members, see <xref conkeyref=”hyperlinks/manage_guest_access_Teams”/>.</p>
To further internationalize your source content, we recommend that you use the same sentence construction for cross-references throughout your documentation set. Doing so will make both your source content and localized versions more consistent.
In French, the reference file link gets translated consistently:
<?xml version=”1.0″ encoding=”UTF-8″?>
<!DOCTYPE topic PUBLIC “-//OASIS//DTD DITA Topic//EN” “topic.dtd”>
<topic id=”hyperlinks” xml:lang=”fr-FR”>
<title>hyperlinks</title>
<body>
<section>
<xref id=”manage_guest_access_Teams” format=”html”
href=”https://docs.microsoft.com/fr-fr/microsoftteams/manage-guests” scope=”external”>Gérer l’accès invité dans Microsoft Teams</xref>
</section>
</body>
</topic>
Both the link and text exactly match the actual content.
In the topics, the content is consistent and easier to translate:
<p>Veuillez-vous reporter à <xref conkeyref=”hyperlinks/manage_guest_access_Teams”/>.</p>
OR
<p>Pour configurer les membres extérieurs de votre projet, voir : <xref conkeyref=”hyperlinks/manage_guest_access_Teams”/>.</p>
This method also enables you to save money since there are fewer words to translate.
Hyperlink maintenance
Now that all the hyperlinks are in a reference table and only created once, you can include them in your regular maintenance schedule and check them at least quarterly. If you have the technical skills available, you can even automate this task.
Any publishing will automatically take the last release and correctly publish all the links.
Conclusion
By using reference files to externalize the hyperlinks, you facilitate maintenance and consistency:
- Easy link testing,
- Consistency between the anchor text and the target title,
- Consistency across all languages.
Also, you save significant effort in maintaining and checking these links.
