diff options
| author | Jonas Smedegaard <dr@jones.dk> | 2021-11-28 14:30:39 +0100 |
|---|---|---|
| committer | Jonas Smedegaard <dr@jones.dk> | 2021-11-28 14:31:52 +0100 |
| commit | 857a2b37dde7b704f42a8fbb5b51f6e593d0cde6 (patch) | |
| tree | 1dd7c3e17f4d9a42c9b6b9dcbe02884cc94601c9 | |
| parent | 4b8173115b6db5fd5c80e614e88d897d98ec30db (diff) | |
SETUP: cover machine-targeted files; cover document formats; recommend to follow Diátaxis documentation system
| -rw-r--r-- | SETUP.md | 39 |
1 files changed, 35 insertions, 4 deletions
@@ -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, |