Kam sodi dokumentacija

Kar mora ostati usklajeno z določenim commitom, vejo ali izdajo, sodi v repozitorij paketa; kar odgovarja na vprašanja uporabnikov in skrbnikov, sodi v wiki.

Veljavnost

Velja od: 26. septembra 2026
Sprejel: The White Knight Labs kot upravljavec tega wikija
Velja za:
- lastne pakete DokuWiki v projektu DokuWiki-Plugins (29 paketov, katerih imena se začnejo z wk)
- njihove repozitorije
- njihove strani v wikiju pod <lang>:wiki:dwe:<package>
- strani za sodelujoče pod <lang>:wiki:help:projects
Prednost: Ta stran je merodajno besedilo pravila. Kratki povzetki drugje – hišna navodila za pisanje dokumentacije in datoteke CONTRIBUTING – se sklicujejo nanjo. Če se od nje razlikujejo, velja ta stran.

Namen

Vsak podatek ima eno samo mesto, zato mu ne more nasprotovati druga različica.

Preden je pravilo začelo veljati, je popis pokazal, kaj povzroča dvojno vzdrževanje. Vseh 29 paketov je imelo uporabniško dokumentacijo dvakrat: kot angleške datoteke Markdown v repozitoriju in kot strani v wikiju v največ petih jezikih. Isto temo je obravnavalo 145 parov dokumentov; pri skoraj vseh sta se besedili ujemali le delno. Poleg tega sta 202 trditvi odstopali od kode. Trije primeri:

Referenca vtičnika za meni je navedla le 2 od njegovih 5 nastavitev.
Datoteka README je opisovala skladnjo, ki je vtičnik ne prepozna.
Privzete vrednosti v wikiju so nasprotovale kodi.

Kopirana datoteka README je v desetih tednih razpadla na tri različna besedila: kopijo v wikiju, različico v repozitoriju in nameščeno datoteko.

Komu je namenjena

Pravilo je namenjeno vsem, ki pišejo strani v wikiju, prispevajo k paketom, kot vzdrževalci skrbijo za pakete ali pregledujejo spremembe.

Temeljna načela

Kontrolno vprašanje: Ali mora podatek ostati usklajen z določenim commitom, vejo ali izdajo? Če da, sodi v repozitorij paketa. Če ne in podatek odgovarja na vprašanje uporabnika ali skrbnika, sodi v javni wiki.
Referenca je ob kodi. Javni vmesnik, skladnja, konfiguracijski ključi (s tipom in privzeto vrednostjo) in pogodbe so opisani v repozitoriju, v datoteki docs/api-reference.md v angleščini. Stran reference posameznega paketa v wikiju je kažipot: pove, kaj referenca vsebuje, in vodi na zaslon repozitorija v projektu. Tam je datoteko mogoče prebrati v kateri koli veji in pri katerem koli commitu. Wiki reference ne kopira in je ne vdeluje.
Povezava namesto kopije. Med repozitorijem in wikijem se nikoli ne kopira. Namesto tega se povezuje, ali pa se vsebina na drugem mestu samodejno ustvari iz prvega. Kopija, ki jo mora kdo ročno usklajevati, se sčasoma oddalji od izvirnika – to dokazuje popis v razdelku Namen.
»Najprej dokumentacija« je način dela, ne hierarhija. Specifikacija lahko nastane pred kodo. Od izdaje naprej je merodajna koda: besedilo se prilagodi temu, kar koda dejansko počne, oznaka »specifikacija« pa se odstrani.
Vsako mesto ima svoj jezik. Datoteke Markdown v repozitoriju so samo v angleščini. Strani v wikiju so v nemščini, angleščini in slovenščini; vsaka različica je napisana neposredno v svojem jeziku na podlagi preverjenih dejstev in jo pregledajo uredniki tega jezika. Iz druge različice se nikoli ne prevaja. Delovni elementi ter besedila commitov in zahtevkov za združitev (pull request) so lahko v nemščini. Imena datotek in imenskih prostorov so vedno angleška, ne glede na jezik vsebine.
Dokumentacija sledi pravicam projekta. Vsaka dokumentacija je vidna natanko tako kot projekt, ki mu pripada. Projekt DokuWiki-Plugins je javen, zato so javne tudi datoteke README njegovih paketov in datoteke v mapi docs/.

Podrobna pravila

Mesto glede na vsebino

Vsebina	Mesto
pregled, hitri začetek, vodnik, navodila in diagnostika napak za uporabnike in skrbnike; namestitev in posodobitev; pojmi izdelka	wiki: `<lang>:wiki:dwe:<package>:*`
javni vmesnik, skladnja in parametri oznak, konfiguracijski ključi s tipom in privzeto vrednostjo, pogodbe	repozitorij: `docs/api-reference.md` in `docs/contract-*.md` (v angleščini); v wikiju stran `<lang>:wiki:dwe:<package>:reference` kot kažipot
zahteve in odvisnosti	repozitorij: `wkcomponent.json`; matrika komponent v wikiju se ustvari iz te datoteke
zgodovina različic	repozitorij: `CHANGELOG.md`, če ga paket ima, sicer zgodovina commitov; nikoli stran v wikiju
odločitve; zapiski brez odločitve	repozitorij: `docs/adr/NNNN-<slug>.md`; `docs/notes/<slug>.md`
notranja arhitektura, pregled razredov in datotek, notranje delovanje shranjevanja podatkov	repozitorij: `docs/architecture.md`
gradnja, razvojno okolje in testi posameznega paketa	repozitorij: `docs/development.md` in `CONTRIBUTING`
model groženj	repozitorij: `docs/threat-model.md`
`README`	repozitorij, kot kažipot: kaj je paket, povezave na njegove strani v wikiju, zahteve, zgradba repozitorija, razvoj, seznam sprememb, licenca
pot do sodelovanja, skupna vsem projektom: dostop, kloniranje, oddaja spremembe, trenutno stanje pravil	wiki: `<lang>:wiki:help:projects:*`

Mesto glede na plast

Plasti od L1 do L6 izhajajo iz modela plasti v hišni smernici za dokumentacijo.

Plast	Mesto
L1 – pregled in začetna stran	wiki
L2 – vodnik in navodila	wiki
L3 – diagnostika napak (naslovi navajajo simptome)	wiki
L4 – pojmi	wiki za pojme izdelka; repozitorij (`docs/architecture.md`) za notranje delovanje
L5 – referenca (javni vmesnik, konfiguracija)	repozitorij; wiki povezuje nanjo
L5 – notranja referenca	repozitorij
L6 – tehnični zapiski, odločitve, seznam sprememb	repozitorij

Povezave med repozitorijem in wikijem

Smer	Postopek
iz wikija v repozitorij	Povezava na zaslon repozitorija v projektu. Kot kontekst služi začetna stran paketa v bralčevem jeziku, zato vmesnik ostane v tem jeziku. Oblika: `[[<lang>:wiki:dwe:<package>:start?do=wkdoadogit_repo&ns=code:dokuwiki-plugins:<package>&file=/docs/api-reference.md\|…]]`. Zaslon najprej prikaže privzeto vejo `main`; druge veje in posamezne commite izberete tam. Za branje račun ni potreben, za kloniranje in prenos arhiva ZIP pa se je treba prijaviti.
iz repozitorija v wiki	absolutna povezava na angleško stran, na primer `https://www.wvds.it/wiki/doku.php?id=en:wiki:dwe:<package>:start`. Izbira jezika na strani vodi do drugih štirih jezikov.
ni dovoljeno	kopije datotek iz repozitorija kot mediji v wikiju; datoteke v repozitoriju, ustvarjene iz strani v wikiju; vdelane datoteke iz repozitorija na straneh paketov

Jezik glede na mesto

Mesto	Jezik
repozitorij: `README`, `docs/**`, `CHANGELOG`, `CONTRIBUTING`, komentarji v kodi	samo angleščina
strani v wikiju	nemščina, angleščina in slovenščina; vsaka različica je napisana v svojem jeziku na podlagi preverjenih dejstev in jo odobrijo uredniki tega jezika; besedila vmesnika se navajajo natanko tako, kot jih vmesnik prikazuje v tem jeziku
delovni elementi, sporočila commitov, opisi zahtevkov za združitev	dovoljena je tudi nemščina
imena datotek in map, imenski prostori, ID-ji strani, imena medijskih datotek	vedno angleščina; ID-ji jezikovnih različic iste strani se razlikujejo le v prvem delu

Jezikovni viri

Hišni priročnik: Slovenski slogovni priročnik
Normativna podlaga: Fran (ISJ ZRC SAZU) s SSKJ in Slovenskim pravopisom

Sorodne teme

Sodelovanje – vloge in poti za prispevanje sprememb
Stanje pravil o prispevkih – kaj je za prispevke trenutno določeno in kaj je še odprto
Slovenski slogovni priročnik – hišni priročnik za slovenska besedila