# Technical setup of feature structure


## Documents

A feature contains texts and scripts,
each targeting one of 4 audiences:

 1. Decision makers
    + General README text: file `README.md`
    + Overview text: file `OVERVIEW.md`
 2. Users
    + Getting started text: `INTRO.md`
    + Usage text: `USE.md`
    + User-facing scripts
 3. Technicians
    + 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.

Generated files should not be tracked with git
(instead created and cleaned with `make` as needed).


### 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,
and ideally ends as globally reusable and long-term maintained.

 1. personal
 2. site-specific
 3. system-integrated Redpill (packaged unofficially)
 4. system-integrated Debian (packaged officially)

Personal drafts are kept in `$HOME`,
with scripts prefixed "my" symlinked to `$HOME/bin`.

Site-specific drafts are kept below `/usr/local`,
with scripts prefixed "local" symlinked to either `/usr/local/bin`
or `/usr/local/sbin`.


## Extensions

One feature may serve as foundation
for one or more extended features.


### Example: Box

 1. Couchdesign: Musicbox - Jukebox service
 2. Redpill: Sohobox - Groupware services (email, filesharing, calendar)
 3. Debian: Box, deploying a system onto hardware using [Boxer][]

[Boxer]: https://wiki.debian.org/Boxer
  "Boxer - helper tool for composing Debian Blends"


## Variability

A mature feature may need local adaptation
for refinements unsuitable for general reuse.


### Example: Account

Feature "account" vary in documentation
(e.g. welcome page for new users)
as well as maintenance routines
(e.g. for account creation, expiry, and backup),
whether an organization offers shell access,
mail, and/or filesharing.


### Example: Print

 1. Siri:
    +`myprint-foo` script tailored to unique color proofing
 2. CouchDesign:
    + `localprint_draft`script tailored inhouse printer
    + `box-print` Boxer profile for in-house print queue service
 4. Redpill: Generic guides to printing

TODO: Rewrite examples to not confusingly reference specific networks.


## Localization

English is used as main language.
Translations are tracked using gettext `*.po` files
tracked using `po4a`.


## Compilation

Features are compiled together
using `mkdocs` and `po4a`
to form a coherent documentation bundle.

### Internationalisation

A gettext template (a.k.a. a pot) file is generated using `po4a`,
extracting all strings from master documents:

	make pot

The generated gettext template file should be tracked in the git.


### Localisation

For each localized language,
Create/update a corresponding gettext (a.k.a. po) file
using a gettext editor.

TODO: Recommend gettext editors for various operating systems.

The edited gettext file should be tracked in the git.


### Publication

Localised markdown files are generated using `po4a`,
and a website is generated using `mkdocs`.

Local preview:

	make watch

Publish:

	make

TODO: Actually implement above commands for all features.