Cross-Referencing — Linking Standards for Technical Documentation

In this tutorial, you will learn about Cross. We cover key concepts, practical examples, and best practices to help you master this topic.

Cross-referencing connects related documentation pages through links. Consistent cross-referencing helps readers navigate and helps search engines understand content relationships. Good cross-references reduce the need to duplicate content.

In this lesson, you will learn standards for cross-referencing in technical documentation.

What You'll Learn

You will understand link text best practices, choose between relative and absolute URLs, use same-page anchors, and implement consistent cross-reference patterns.

Why It Matters

Well-crafted cross-references guide readers to the information they need. Bad cross-references create dead ends and frustrate readers.

Real-World Use

DodaTech documentation cross-references every tutorial to the relevant reference page. Readers move from learning a task to looking up details without searching.

flowchart LR
  A[Tutorial] --> B[Related How-To]
  A --> C[Reference Page]
  A --> D[Conceptual Guide]
  B --> E[Reader Gets Full Context]
  C --> E
  D --> E
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Link Text Rules

Use descriptive link text that tells readers where the link goes. See the DodaZIP installation guide not Click here.

Include keywords in link text. The compression algorithm reference page is better than This page.

Do not use raw URLs as link text. https://docs.dodatech.com/dodazip/install/ becomes the DodaZIP installation guide.

Keep link text concise. A sentence-long link is hard to read. Keep it under five words.

# Good link text
See the [DodaZIP installation guide](/dodazip/install/) for setup instructions.
Learn about [streaming compression](/dodazip/concepts/streaming/).

# Bad link text
Click [here](/dodazip/install/) for setup instructions.
Go to [https://docs.dodatech.com/dodazip/install/](https://docs.dodatech.com/dodazip/install/)

URL Conventions

Use relative URLs for links within the same documentation set. Relative URLs work in all environments without modification.

Use absolute URLs for links to external sites. Verify external links periodically.

Use descriptive URL paths. /dodazip/install/ not /page?id=123. Descriptive URLs are readable and SEO-friendly.

Do not include file extensions in URLs. /dodazip/install/ not /dodazip/install.html.

# Relative URLs (same site)
[Installation guide](/dodazip/install/)
[Configuration reference](/dodazip/reference/configuration/)

# Absolute URLs (external)
[Python.org](https://www.python.org/)

Common Mistakes

1. Click Here Links

Generic link text that does not describe the destination. Readers cannot tell where the link goes.

2. Raw URLs as Link Text

Full URLs displayed instead of descriptive text. They look ugly and are not accessible.

3. Broken Links

Links to pages that no longer exist. Check links periodically.

4. Over-Linking

Linking every other word. Readers cannot distinguish important links from decorative ones.

5. Same-Page Anchors Without Context

Jumping to an anchor without telling readers what the section contains.

6. No Link to Related Content

Pages that end without suggesting where to go next.

7. Inconsistent URL Formatting

Using relative in some places and absolute in others for links within the same site.

Practice Questions

1. What makes good link text?

Descriptive text that tells readers where the link goes and includes relevant keywords.

2. Why use relative URLs for same-site links?

Relative URLs work in all environments including local development without modification.

3. What should you avoid in link text?

Click here, read more, this page. Generic text that does not describe the destination.

4. How do you handle links to external sites?

Use absolute URLs and verify them periodically. External links can break without notice.

5. Challenge: Audit a documentation page for cross-reference issues. Find five violations of link text best practices and five opportunities for new cross-references.

FAQ

Mini Project

Create a cross-referencing style guide for a documentation project. Include rules for link text, URL format, same-page anchors, external links, and link maintenance. Audit existing pages and fix violations.

What's Next

Next: Creating Your Own Style Guide