Dokumentaation elinkaaristrategia

DevSecOps‑sisällön pitkäikäisyys + päivitettävyys

Tämä dokumentti kuvaa mallin, jonka avulla tekninen dokumentaatio pysyy ajan tasalla, selkeänä ja helposti ylläpidettävänä. Malli perustuu elinkaariajatteluun, jossa sisältö jaetaan kolmeen kerrokseen: stable, rolling ja volatile.
Tavoitteena on rakentaa dokumentaatio, joka toimii kuten tuotantojärjestelmä: ennustettavasti, hallitusti ja jatkuvasti paranevasti.

1. Sisällön jakaminen kolmeen kerrokseen

A. Hitaasti vanheneva tieto (Core Knowledge – stable)

Tähän kuuluvat:

Linux‑perusteet
Git
Verkot
Tietokannat
Ohjelmoinnin peruslogiikka
DevOps‑periaatteet

Elinkaari: 5–10 vuotta
Merkintä: status: stable

B. Keskinopeasti vanheneva tieto (Evolving Practices – rolling)

Esimerkiksi:

Docker
CI/CD‑työkalut
Python/Node‑kirjastot
Pilviympäristöjen käytännöt

Elinkaari: 1–3 vuotta
Merkintä: status: rolling

C. Nopeasti vanheneva tieto (Fast‑moving Security – volatile)

Esimerkiksi:

AppSec‑työkalut
SAST/SCA/DAST‑konfiguraatiot
CVE‑tilanne
Turvalliset oletusasetukset

Elinkaari: 6–12 kuukautta
Merkintä: status: volatile

2. Kansiorakenne, joka tukee elinkaarta

Voit lisätä Scenes‑rakenteen sisään kolme tasoa: * scenes/ * prologue/ * stable/ * rolling/
* volatile/

Esimerkkejä: - scenes/prologue/stable/git/ - scenes/prologue/rolling/docker/ - scenes/prologue/volatile/appsec/

Tämä tekee päivityksestä helppoa:

→ kun jokin vanhenee, näet heti missä se sijaitsee.

3. Metadata jokaisen sivun alkuun

Lisää jokaisen Markdown‑sivun alkuun YAML‑metadata:

Stable‑sisältö

status: stable
last_reviewed: 2026-01-26
update_cycle: 24 months
owner: mikko

Volatile‑sisältö

status: volatile
last_reviewed: 2026-01-26
update_cycle: 6 months
owner: mikko

Metadata antaa: - näkyvyyden siihen, mikä pitää päivittää - muistutuksen päivitysrytmeistä - mahdollisuuden automatisoida tarkistuksia myöhemmin

4. Päivitysrytmi

Stable (24 kk)

Tarkista 24 kuukauden välein
Päivitä vain, jos perusperiaatteet muuttuvat

Rolling (12–18 kk)

Tarkista vuosittain
Päivitä työkalujen versiot ja parhaat käytännöt

Volatile (3–6 kk)

Tarkista 2–4 kertaa vuodessa
Päivitä AppSec‑työkalut, CVE‑esimerkit ja suositukset

5. “Deprecated”‑polku

Kun jokin tieto vanhenee, älä poista sitä — siirrä se: archive/deprecated/

Lisää tiedoston alkuun:

deprecated: true
reason: replaced-by-new-tooling
date: 2026-01-26

6. Changelog dokumentaatiolle

Luo tiedosto: docs/CHANGELOG.md

## 2026-01-26
- Updated AppSec scanning examples
- Moved old Docker best practices to deprecated/
- Added stable/rolling/volatile structure

Changelog tekee dokumentaatiosta projektin, ei irrallisten tiedostojen kokoelman.

7. Review Dashboard

Luo: docs/review-dashboard.md

Sisältöehdotus:

Lista sivuista, joiden last_reviewed on vanhempi kuin update_cycle
Lista volatile‑sisällöstä
Lista deprecated‑sisällöstä

Dashboard toimii dokumentaation “operational view” ‑näkymänä.

Mikä on RepoStage‑ekosysteemi

RepoStage‑ekosysteemi on kokonaisuus, joka yhdistää dokumentaation, oppimispolut ja teknisen arkkitehtuurin yhdeksi yhtenäiseksi järjestelmäksi. Se toimii sekä projektin “selkärankana” että oppimisympäristönä, jossa kaikki tieto on modulaarista, versionhallittua ja pitkäikäistä. RepoStage ei ole pelkkä dokumentaatio, vaan ekosysteemi, joka rakentuu kolmesta peruspilarista:

Scenes – tarinallinen oppimispolku, joka kuvaa DevSecOps‑matkan vaihe vaiheelta.
Archive – tekninen tietopankki, jossa syventävät ohjeet, blueprintsit ja teknologiamuistiinpanot elävät omissa moduuleissaan.
Lifecycle Model – stable/rolling/volatile‑kerrokset, jotka tekevät dokumentaatiosta itseään ylläpitävän ja ennustettavan.

RepoStage‑ekosysteemi tarjoaa rakenteen, jossa tieto ei kasaannu hallitsemattomasti, vaan elää hallitusti kuten moderni infrastruktuuri. Se on suunniteltu tukemaan pitkäaikaista kehitystä, jatkuvaa parantamista ja DevSecOps‑ajattelun mukaista näkyvyyttä koko projektin elinkaareen.

Dokumentaatiostrategia & RepoStage‑ekosysteemin integraatio

RepoStage hyödyntää dokumentaation elinkaarimallia tehdäkseen sisällöstä pitkäikäistä, hallittua ja helposti päivitettävää. Malli jakaa kaiken tiedon kolmeen kerrokseen: stable, rolling ja volatile, mikä selkeyttää ylläpitoa ja tekee dokumentaatiosta yhtä ennustettavan kuin infrastruktuuri.
Tämä strategia toimii rinnakkain RepoStage‑ekosysteemin kanssa, jossa dokumentaatio, oppimispolut ja tekninen kirjasto muodostavat yhtenäisen, itseään ylläpitävän kokonaisuuden.

🔧 Keskeiset ominaisuudet

Stable / Rolling / Volatile ‑kerrokset
Selkeä rakenne hitaasti, keskinopeasti ja nopeasti vanhenevalle tiedolle.
Metadata‑ohjattu elinkaariseuranta
Jokaisella sivulla on status, last_reviewed, update_cycle ja owner.
Päivitysrytmi sisäänrakennettuna
Dokumentaatio kertoo itse, milloin mikäkin osa on vanhentumassa.
Review Dashboard
Yksi näkymä, joka listaa päivitystä vaativat sivut ja riskialueet.
Changelog dokumentaatiolle
Versionhallittu muutoshistoria, joka tekee dokumentaatiosta “tuotteen”.
Deprecated‑polku
Vanha tieto arkistoidaan turvallisesti ilman linkkien katkeamista.
Modulaarinen kansiorakenne
Sama logiikka kuin RepoStagen infrastruktuurissa: jokainen osa on oma moduulinsa.
Laajennettavuus ilman rakenteen rikkoutumista
Uusia teknologioita voi lisätä mihin tahansa kerrokseen.
DevSecOps‑henkinen jatkuva parantaminen
Dokumentaatio noudattaa samaa filosofiaa kuin RepoStagen infra ja pipeline‑mallit.

RepoStage‑ekosysteemin rooli

RepoStage toimii dokumentaatiostrategian rinnakkaisena ekosysteeminä, jossa:

Scenes tarjoaa tarinallisen oppimispolun
Archive toimii teknisen tiedon kirjastona
Lifecycle Model varmistaa tiedon pitkäikäisyyden ja päivitettävyyden

Näiden yhdistelmä tekee RepoStagesta kokonaisuuden, jossa dokumentaatio ei ole staattinen, vaan elävä, versionhallittu ja hallitusti kehittyvä järjestelmä.

Kuinka RepoStage auttaa dokumentaation ylläpidossa

RepoStage toimii dokumentaation ylläpidon tukijärjestelmänä, joka varmistaa, että tieto pysyy ajan tasalla ja rakenteeltaan hallittuna. Ekosysteemi tarjoaa selkeän, modulaarisen rakenteen, jossa jokainen dokumentti elää oman elinkaarensa mukaisesti. Stable/rolling/volatile‑kerrokset kertovat heti, mikä sisältö on pysyvää ja mikä vaatii säännöllistä tarkistusta. Metadata (status, last_reviewed, update_cycle, owner) tekee ylläpidosta läpinäkyvää ja mahdollistaa sen, että dokumentaatio “valvoo itse itseään”.

Review Dashboard kokoaa yhteen kaikki päivitystä vaativat sivut, jolloin ylläpito ei perustu muistiin vaan näkyvään listaan. Changelog puolestaan tallentaa kaikki muutokset, mikä helpottaa seurantaa ja auditointia. Deprecated‑polku säilyttää vanhentuneen tiedon turvallisesti ilman linkkien katkeamista. Yhdessä nämä ominaisuudet tekevät RepoStagesta järjestelmän, joka tukee dokumentaation jatkuvaa parantamista ja vähentää manuaalista ylläpitotyötä merkittävästi.

Lopputulos

Tämän mallin avulla dokumentaatio:

ei vanhene hallitsemattomasti
on jaettu elinkaaren mukaan
sisältää metadatan, joka kertoo päivitysrytmin
on helppo päivittää
säilyttää historiansa
toimii kuten oikea tuotantojärjestelmä

Tämä on DevSecOps‑ajattelua parhaimmillaan: jatkuvaa parantamista, näkyvyyttä ja hallittua muutosta.