đź“‘ Repostage: Dokumentaation aggregointikerros¶
Repostage on Developer Portal, joka kokoaa hajautetun dokumentaation yhdeksi navigoitavaksi kokonaisuudeksi. Se ei luo sisältöä, vaan toimii siltana koodirepositorioiden ja loppukäyttäjien välillä.
🎯 Perusfilosofia¶
- Dokumentaatio elää repossa: Sisältö on aina koodin vieressä.
- Repostage vain julkaisee: Se on passiivinen lukija, joka ei koskaan kirjoita takaisin projekteihin.
- Source of Truth: Git-historia on ainoa totuuden lähde (omistajuus, audit trail, PR-prosessit).
🏛️ Roolit ja tehtävänjako¶
| Rooli | Vastuualue | Keskeiset tehtävät |
|---|---|---|
| Projektitiimi | Sisällön omistajuus | Markdown-kirjoittaminen, ADR:t, kaaviot, docs/-ylläpito. |
| Standardointi | Rakenteen hallinta | Projektitemplatet, yhteiset mkdocs.yml-pohjat. |
| Repostage | Aggregointi ja jakelu | Repojen skannaus, hakuindeksointi, portaalin julkaisu. |
đź“ś Dokumentoinnin pelisäännöt¶
- Docs-as-Code: Dokumentaatio on osa lähdekoodia. Se versioidaan ja katselmoidaan samalla tavalla kuin koodi.
- Yhtenäinen rakenne: Jokaisessa projektissa on oltava
docs/-hakemisto jamkdocs.yml-konfiguraatio. - Ei duplikointia: Jos tieto on jo toisessa repossa, viittaa siihen linkillä portaalin kautta. Älä kopioi tiedostoja.
- Automaatio ensin: Kaikki julkaisu tapahtuu CI/CD-putken kautta. Portaaliin ei tehdä manuaalisia muutoksia.
🏗️ Paikallinen Repo vs. Repostage¶
1. Paikallisen repositorion rooli (Lähde)¶
Repositorio vastaa kysymykseen: "Miten tämä nimenomainen komponentti toimii?" * Sisältö: README.md, arkkitehtuurikuvaukset, API-määrittelyt (OpenAPI), ADR-dokumentit. * Konfiguraatio: Paikallinen mkdocs.yml määrittelee projektin sisäisen navigaation.
2. Repostagen rooli (Portaali)¶
Repostage vastaa kysymykseen: "Miten koko ekosysteemi toimii ja mistä löydän tarvitsemani tiedon?" * Aggregointi: Yhdistää satojen repojen navigaatiot yhdeksi puuksi. * Globaali haku: Mahdollistaa tiedon etsimisen kaikista organisaation projekteista kerralla. * Brändäys: Pakottaa yhtenäisen visuaalisen ilmeen ja standardit.
🧩 Milloin käyttää mitäkin?¶
- MkDocs repossa: Riittää itsenäisiin projekteihin tai kirjastoihin, joilla ei ole riippuvuuksia muuhun organisaatioon.
- Repostage: Välttämätön mikropalveluarkkitehtuureissa, suurissa organisaatioissa ja tilanteissa, joissa dokumentaatio on hajautunut useisiin eri tyyppisiin repositorioihin (esim. infra, koodi ja tietoturva erikseen).
Tämä malli varmistaa, että järjestelmä ei paisu hallitsemattomaksi, vastuut ovat selkeät ja kehittäjäkokemus (DX) pysyy korkeana.