Authoring guidelines: Mention "Diátaxis" approach

Author: amotl

style/general.rst

@@ -2,6 +2,30 @@
 General Conventions
 ===================
 
+Approach
+========
+
+`Diátaxis`_ is a systematic approach to technical documentation authoring.
+
+Loosely 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.
+
+Consistency
+===========
+
 Consistency makes collaboration easier. To that end, please try to follow the
 applicable general conventions.
 
@@ -14,3 +38,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/