diff options
author | Jonas Smedegaard <dr@jones.dk> | 2018-11-29 04:27:44 +0100 |
---|---|---|
committer | Jonas Smedegaard <dr@jones.dk> | 2018-11-29 04:27:44 +0100 |
commit | 6c8e0ea6fa47b1e4774211391d4177857745063d (patch) | |
tree | 4dfe88466a33ce3f800cfec6550c39486e364ea4 | |
parent | d233ca2249080bc296af07eccacf2e86806f41ba (diff) |
Document text writing style. Update TODOs.
-rw-r--r-- | ADMIN.md | 33 | ||||
-rw-r--r-- | TODO | 5 |
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" @@ -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 |