From 91d8f3bf85551e3e69128f8d3da8fc0d238df7a3 Mon Sep 17 00:00:00 2001 From: Samuel Lijin Date: Wed, 25 Jun 2025 13:03:22 -0700 Subject: [PATCH] Make reference-explanation.rst more self-consistent Update the introductory paragraph to, when comparing reference and explanation, to lead with reference, for consistency with the title of the page. This was somewhat confusing to me when I was reading this page, because I assumed that it was relating reference to acquisition and explanation to application, and then I got further down the page and it was the other way around. --- reference-explanation.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/reference-explanation.rst b/reference-explanation.rst index 89da55a..7cdc80f 100644 --- a/reference-explanation.rst +++ b/reference-explanation.rst @@ -3,12 +3,12 @@ The difference between reference and explanation ================================================ -Explanation and reference both belong to the *theory* half of the Diátaxis map - they don't contain +Reference and explanation both belong to the *theory* half of the Diátaxis map - they don't contain steps to guide the reader, they contain theoretical knowledge. -The difference between them is - just as in the difference between tutorials and how-to guides - the -difference between the *acquisition* of skill and knowledge, and its *application*. In other words -it's the distinction between *study* and *work*. +The difference between them is - just as in the difference between tutorials and how-to guides - that +reference is used in the *application* of skill and knowledge, whereas explanation is used for the +*acquisition* of skill and knowledge. In other words, it's the distinction between *work* and *study*. A straightforward distinction, *mostly*