From b9bc029977acdead72cbcb92f78669d7235182e8 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Thu, 16 May 2019 17:56:31 +0100 Subject: [PATCH] docs: Advise use of non-interactive commands If a doc contains commands, they should be non-interactive where possible to allow for the possibility of automating the testing of the document in the CI. Fixes #477. Signed-off-by: James O. D. Hunt --- Documentation-Requirements.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation-Requirements.md b/Documentation-Requirements.md index a1a1d60061..ea5501d27e 100644 --- a/Documentation-Requirements.md +++ b/Documentation-Requirements.md @@ -28,6 +28,13 @@ All documents must: If you are adding a new document, ensure you add a link to it in the "closest" `README` above the directory where you created your document. +- If the document needs to tell the user to manipulate files or commands, use a + [code block](#code-blocks) to specify the commands. + + If at all possible, ensure that every command in the code blocks can be run + non-interactively. If this is possible, the document can be tested by the CI + which can then execute the commands specified to ensure the instructions are + correct. This avoids documents becoming out of date over time. # Linking advice