aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJonas Smedegaard <dr@jones.dk>2021-11-28 14:30:39 +0100
committerJonas Smedegaard <dr@jones.dk>2021-11-28 14:31:52 +0100
commit857a2b37dde7b704f42a8fbb5b51f6e593d0cde6 (patch)
tree1dd7c3e17f4d9a42c9b6b9dcbe02884cc94601c9
parent4b8173115b6db5fd5c80e614e88d897d98ec30db (diff)
SETUP: cover machine-targeted files; cover document formats; recommend to follow Diátaxis documentation system
-rw-r--r--SETUP.md39
1 files 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,