From 857a2b37dde7b704f42a8fbb5b51f6e593d0cde6 Mon Sep 17 00:00:00 2001
From: Jonas Smedegaard <dr@jones.dk>
Date: Sun, 28 Nov 2021 14:30:39 +0100
Subject: SETUP: cover machine-targeted files; cover document formats;
 recommend to follow Diátaxis documentation system
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 SETUP.md | 39 +++++++++++++++++++++++++++++++++++----
 1 file changed, 35 insertions(+), 4 deletions(-)

diff --git a/SETUP.md b/SETUP.md
index 5d83fdb..6981824 100644
--- a/SETUP.md
+++ b/SETUP.md
@@ -4,7 +4,7 @@
 ## Documents
 
 A feature contains texts and scripts,
-each targeting one of 3 audiences:
+each targeting one of 4 audiences:
 
  1. Decision makers
     + General README text: file `README.md`
@@ -17,16 +17,47 @@ each targeting one of 3 audiences:
     + Bootstrapping text: file `SETUP.md`
     + Maintenance text: file `ADMIN.md`
     + Administration scripts
+ 4. Machines
+    + Project metadata: file `doap.ttl`
+    + Bootstrapping script: file `Makefile`
+    + Site variables: file `site.conf`
+    + Build variables (generated): file `built.conf`
+    + Install variables (generated): file `installed.conf`
+
+General README text is mandatory.
+All other parts are optional.
 
-General README text is mandatory,
-and must follow the [standard-readme][] specification.
+Generated files should not be tracked with git
+(instead created and cleaned with `make` as needed).
 
-All other parts are optional.
+
+### Document formats
+
+Files with extension `.md` are in [CommonMark] format.
+README must follow the [standard-readme] specification,
+and other CommonMark files should take inspiration from it as well.
+
+Files with extension `.conf` are basic settings files
+containing only variable settings and comments
+in POSIX `sh` syntax.
+
+[CommonMark]: <https://spec.commonmark.org/>
+  "specification for the Markdown lightweight markup language"
 
 [standard-readme]: <https://github.com/RichardLitt/standard-readme/blob/master/spec.md>
   "specification for how a standard README should look"
 
 
+### Writing style
+
+CommonMark files should use [Diátaxis documentation system],
+i.e. each file should aim at serving only one purpose -
+either `tutorial`, `howto guide`, `reference`, or `background`.
+
+[Diátaxis documentation system]: <https://diataxis.fr/>
+  "systematic framework for technical documentation authoring"
+
+
 ## Maturity
 
 A feature may start as a personal draft,
-- 
cgit v1.2.3