From 780491d91dbaad8957a350c1e8a41f80e295f25a Mon Sep 17 00:00:00 2001
From: Jonas Smedegaard <dr@jones.dk>
Date: Thu, 29 Nov 2018 03:09:16 +0100
Subject: Major rewrite.

---
 README.md | 49 +++++++++++---------------------
 SETUP.md  | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 112 insertions(+), 33 deletions(-)
 create mode 100644 SETUP.md

diff --git a/README.md b/README.md
index 3fb68c7..3da25e3 100644
--- a/README.md
+++ b/README.md
@@ -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.
-- 
cgit v1.2.3