SETUP.md



Technical setup of feature structure
Documents
A feature contains texts and scripts,
each targeting one of 3 audiences:

Decision makers

General README text: file README.md
Overview text: file OVERVIEW.md


Users

Getting started text: INTRO.md
Usage text: USE.md
User-facing scripts


Technicians

Bootstrapping text: file SETUP.md
Maintenance text: file ADMIN.md
Administration scripts


General README text is mandatory,
and must follow the standard-readme specification.
All other parts are optional.
Maturity
A feature may start as a personal draft,
and ideally ends as globally reusable and long-term maintained.

personal
site-specific
system-integrated Redpill (packaged unofficially)
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

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

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

Siri:
+myprint-foo script tailored to unique color proofing
CouchDesign:

localprint_draftscript tailored inhouse printer
box-print Boxer profile for in-house print queue service


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.