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.

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.

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

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_draftscript tailored inhouse printer
    • box-print Boxer profile for in-house print queue service
  3. 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.