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ää projektirepositoriossa: 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-hakemiston ylläpito. |
| Standardointi | Rakenteen hallinta | Projektitemplatet, yhteiset mkdocs.yml-pohjat. |
| Repostage | Aggregointi ja jakelu | Repojen skannaus, hakuindeksointi, portaalin julkaisu. |
Dokumentoinnin pelisäännöt¶
1. Docs-as-Code: Dokumentaatio on osa lähdekoodia. Se versioidaan ja katselmoidaan samalla tavalla kuin koodi. 2. Yhtenäinen rakenne: Jokaisessa projektissa on oltava docs-hakemisto ja mkdocs.yml-konfiguraatio. 3. Ei duplikointia: Jos tieto on jo toisessa repossa, viittaa siihen tekstiviitteellä portaalin nimeämisen mukaisesti. Älä kopioi tiedostoja. 4. Automaatio ensin: Kaikki julkaisu tapahtuu CI/CD-putken kautta. Portaaliin ei tehdä manuaalisia muutoksia.
Lähderepositorio vs. Repostage-portaali¶
1. Yksittäisen repositorion rooli (Tiedon lähde)¶
Yksittäinen repositorio (esim. projekti GitLabissa) vastaa kysymykseen: "Miten tämä nimenomainen komponentti toimii?"
-
Sisältö: README.md, arkkitehtuurikuvaukset, API-määrittelyt (OpenAPI) ja ADR-dokumentit.
-
Konfiguraatio: Projektikohtainen mkdocs.yml määrittelee kyseisen projektin sisäisen rakenteen.
2. Repostage-portaalin rooli (Aggregointi)¶
Repostage vastaa kysymykseen: "Miten koko ekosysteemi toimii ja mistä löydän tarvitsemani tiedon?"
-
Aggregointi: Kerää ja yhdistää useiden eri repositorioiden navigaatiot yhdeksi kokonaisuudeksi.
-
Globaali haku: Mahdollistaa tiedon etsimisen kaikista liitetyistä projekteista yhdellä kertaa.
-
Standardointi: Varmistaa yhtenäisen visuaalisen ilmeen ja dokumentaation laatutason läpi koko organisaation.
Dokumentin tila: Luonnos — Pvm: 13.01.2026