diff --git a/Documentation-Requirements.md b/Documentation-Requirements.md index 3a04615f3b..764ade105f 100644 --- a/Documentation-Requirements.md +++ b/Documentation-Requirements.md @@ -1,5 +1,6 @@ * [Introduction](#introduction) * [General requirements](#general-requirements) +* [Linking advice](#linking-advice) * [Notes](#notes) * [Warnings and other admonitions](#warnings-and-other-admonitions) * [Files and command names](#files-and-command-names) @@ -20,6 +21,18 @@ All documents must: - Include a TOC (table of contents) at the top of the document with links to all heading sections. +# Linking advice + +Linking between documents is strongly encouraged to help users and developers +navigate the material more easily. Linking also avoids repetition - if a +document needs to refer to a concept already well described in another section +or document, do not repeat it, link to it +(the [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) principle). + +Another advantage of this approach is that changes only need to be applied in +one place: where the concept is defined (not the potentially many places where +the concept is referred to using a link). + # Notes Important information that is not part of the main document flow should be