aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJonas Smedegaard <dr@jones.dk>2018-11-29 03:09:16 +0100
committerJonas Smedegaard <dr@jones.dk>2018-11-29 03:31:42 +0100
commit780491d91dbaad8957a350c1e8a41f80e295f25a (patch)
tree242170ff793a9ec4360c88bc6bff39a4c978a339
parentfdeb4c5fb7f73a9567a09c551201be8d30f5389e (diff)
Major rewrite.
-rw-r--r--README.md49
-rw-r--r--SETUP.md96
2 files changed, 112 insertions, 33 deletions
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.