Authoring guidelines: Mention "Diátaxis" approach

Author: amotl

style/general.rst

@@ -2,6 +2,40 @@
 General Conventions
 ===================
 
+Approach
+========
+
+`Diátaxis`_ is a systematic approach to technical documentation authoring.
+
+Following its paradigms,
+there are four main types of documentation:
+tutorials, how-to guides, technical reference, and explanation.
+
+- A tutorial is a practical activity, in which the student learns by doing
+  something meaningful, towards some achievable goal.
+
+- A how-to guide helps the user get something done, correctly and safely;
+  it guides the user’s action.
+
+- Reference material contains propositional or theoretical knowledge that
+  a user looks to in their work.
+
+- Explanations deepen and broaden the reader’s understanding of a subject.
+  They bring clarity, light and context.
+
+.. note::
+
+    **CrateDB documentation loosely follows Diátaxis paradigms.** There is no
+    need to adhere to them too strictly across the board when it is not
+    applicable, or would need too many efforts to refactor or improve
+    existing material.
+
+    It is always good to persue noble goals, but the focus should be on
+    working software.
+
+Consistency
+===========
+
 Consistency makes collaboration easier. To that end, please try to follow the
 applicable general conventions.
 
@@ -14,3 +48,6 @@ We have two core principles:
 
 2. Know when to be inconsistent. Break any of these conventions sooner than
    doing anything foolish.
+
+
+.. _Diátaxis: https://diataxis.fr/

style/repos.rst

@@ -160,17 +160,5 @@ The ``docs`` directory is reserved for use as a Sphinx_ documentation project.
 All Sphinx projects must use a top-level directory named ``docs``.
 
 
-Repo structure
-==============
-
-There are three main types of documentation: tutorials, howtos, and reference.
-
-Tutorials are for step-by-step guides that guide you from beginning to end through a process (e.g., installation or cluster deployment).
-
-Howtos are for guides to performing a single particular operation (e.g., deleting a cluster).
-
-Reference is for reference information (e.g., a list of SQL syntax or an overview of the CrateDB Cloud Console). 
-
-
 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 .. _Sphinx: http://sphinx-doc.org/