Understanding when to use internal versus external links is crucial for effective documentation. Each type serves a different purpose and needs to be used appropriately to provide the best user experience.
Internal Links:
- Use internal links to connect related content within the same documentation set: Internal links help readers navigate between different sections or pages of the documentation. This is useful for guiding users to supplementary content, such as related guides, FAQs, or tutorials. Example: “For a list of supported platforms, see the compatibility page.”
- Maintain consistency in linking: Use consistent link text and formatting throughout the documentation to ensure a smooth user experience. If you use “see” for one internal link (“see the installation guide”), use it consistently for similar references.
- Anchor links within the same page: For long documents, use anchor links to guide readers to specific sections or headings within the same page. Example: “For further details, refer to the troubleshooting section.”
External Links:
- Use external links to direct readers to third-party resources: External links should be used to refer users to resources outside of the organisation’s website, such as industry standards, additional tools, or external APIs. Example: “Learn more about JSON standards.”
- Validate the credibility and relevance of external links: Ensure that all external links point to reputable, authoritative sources. Avoid linking to outdated, unreliable, or unofficial content.
- Regularly review external links: Check that all external links are up to date and functioning correctly. Broken or outdated links can lead to a poor user experience.
Dos:
- Use internal links to connect related content: Example: “See the User Guide for detailed setup instructions.”
- Use external links for authoritative third-party resources: Example: “Visit the ISO website for official standards.”
Don’ts:
- Don’t use external links for information that could be covered internally: Instead, create or link to internal resources where possible.
- Avoid linking to unreliable or unofficial sources: Always choose reputable sites.