diff options
| -rw-r--r-- | README.md | 49 | ||||
| -rw-r--r-- | SETUP.md | 96 |
2 files changed, 112 insertions, 33 deletions
@@ -1,33 +1,16 @@ -# Structure for our project documents - -In documenting setup and use, we destinguish between - - 1. indvidual level (my) - 2. CouchDesign level (our) - 3. Enterprice level (local) - Redpill - 4. Global level - Debian - -## Perspectives - -Our private projects contributes to the bigger picture -Current examples: - -### Musicbox - - 2. Couchdesign: Musicbox - 3. Redpill: Sohobox - 4. Debian: ShowMeBox/ Pure Debian Blends/ Boxer - -### Print - - 1. Mylocalprint (Siris setup and job related scripts) - 2. CouchDesign print box (our) - 4. Debian print documentation - -##Documentation files - -Each documentation area may contain the following files: - - * README - * ADMIN - * USE +# Organisational structure of feature projects + +A feature contains texts and scripts, +each targeting one of 3 audiences: +Decision makers, users, users, and technicians. +As a minimum, +each feature contains an executive summary text. + +A feature may start as a personal draft, +and ideally ends as globally reusable and long-term maintained. +It can serve as foundation for other extended features, +and a mature feature can be shadowed by a local adaptation. + +Features are compiled together +globally and for each site, +presenting features as one coherent documentation bundle. diff --git a/SETUP.md b/SETUP.md new file mode 100644 index 0000000..2eb908d --- /dev/null +++ b/SETUP.md @@ -0,0 +1,96 @@ +# Technical setup of feature structure + + +## Documents + +A feature contains texts and scripts, +each targeting one of 3 audiences: + + 1. Decision makers + + Summary 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` + + Maintainance text: file `ADMIN.md` + + Administration scripts + +Summary text is mandatory. +All other parts are optional. + + +## 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 + + +## 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. |