From dd69931a4cec2feccf26d0d330d83b773516f6e0 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Wed, 8 May 2019 09:37:20 +0100 Subject: [PATCH 1/3] docs: Tighten up general requirements list Simplify the bullet list of general requirements in the documentation requirements document at the same time as making the wording unambiguous. Signed-off-by: James O. D. Hunt --- Documentation-Requirements.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Documentation-Requirements.md b/Documentation-Requirements.md index 29f32405f6..b68ead8af9 100644 --- a/Documentation-Requirements.md +++ b/Documentation-Requirements.md @@ -13,8 +13,10 @@ Containers](https://github.com/kata-containers) project. # General requirements -- All documents are expected to be written in [GitHub Flavored Markdown](https://github.github.com/gfm) format. -- All documents should have the `.md` file extension. +All documents must: + +- Be written in [GitHub Flavored Markdown](https://github.github.com/gfm) format. +- Have a `.md` file extension. # Notes From b5931eb0d6835f2119fd4ecae59f3a6ebc571175 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Wed, 8 May 2019 09:39:39 +0100 Subject: [PATCH 2/3] docs: Add TOC requirement State that all documents should contain a table of contents. Partially fixes: #458. Signed-off-by: James O. D. Hunt --- Documentation-Requirements.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Documentation-Requirements.md b/Documentation-Requirements.md index b68ead8af9..3a04615f3b 100644 --- a/Documentation-Requirements.md +++ b/Documentation-Requirements.md @@ -17,6 +17,8 @@ All documents must: - Be written in [GitHub Flavored Markdown](https://github.github.com/gfm) format. - Have a `.md` file extension. +- Include a TOC (table of contents) at the top of the document with links to + all heading sections. # Notes From ad87c6cc649dc0bf2bc119c621841d57dfba3383 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Wed, 8 May 2019 09:46:51 +0100 Subject: [PATCH 3/3] docs: Add linking advice section Add a new "Linking advice" section to the documentation requirements document. Fixes: #458. Signed-off-by: James O. D. Hunt --- Documentation-Requirements.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) 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