aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJonas Smedegaard <dr@jones.dk>2018-11-29 04:27:44 +0100
committerJonas Smedegaard <dr@jones.dk>2018-11-29 04:27:44 +0100
commit6c8e0ea6fa47b1e4774211391d4177857745063d (patch)
tree4dfe88466a33ce3f800cfec6550c39486e364ea4
parentd233ca2249080bc296af07eccacf2e86806f41ba (diff)
Document text writing style. Update TODOs.
-rw-r--r--ADMIN.md33
-rw-r--r--TODO5
2 files changed, 37 insertions, 1 deletions
diff --git a/ADMIN.md b/ADMIN.md
new file mode 100644
index 0000000..32523c1
--- /dev/null
+++ b/ADMIN.md
@@ -0,0 +1,33 @@
+# Maintenance of feature structure
+
+Writing style of documentation files,
+coding style of scripts,
+and how to handle translation, preview, and compilation.
+
+
+## Documentation
+
+Texts are written in [CommonMark][] -
+a strict flavor of Markdown.
+
+Use [ATX headings][] and [semantic linewrapping][].
+
+Use [reference links] (shortcut style where possible),
+with its reference definition at bottom of same section.
+
+Avoid [hard line breaks][].
+
+[CommonMark]: <https://commonmark.org/>
+ "CommonMark - strongly defined, highly compatible specification of Markdown"
+
+[ATX headings] <https://en.wikipedia.org/wiki/Aaron_Swartz#Markdown>
+ "ATX headings - header markup using leading hashtags"
+
+[semantic linewrapping]: <https://scott.mn/2014/02/21/semantic_linewrapping/>
+ "semantic linewrapping - wrap by paragraph or shorter semantic chunks"
+
+[reference links]: <https://spec.commonmark.org/0.28/#reference-link>
+ "reference links - link markup with metadata in separate source paragraph"
+
+[hard line breaks]: <https://spec.commonmark.org/0.28/#soft-line-breaks>
+ "hard line breaks - markup to force linebreak within a paragraph"
diff --git a/TODO b/TODO
index 5488842..8b74c9b 100644
--- a/TODO
+++ b/TODO
@@ -2,5 +2,8 @@
* Add illustration of structure.
* Document navigation structure.
- * Document maintenance of documentation.
* Document script conventions.
+ * Document text localization
+ * Document text macros
+ * Service, host, and domain expansion
+ * Maturity tagging