Kako prispevati k dokumentaciji

Prispevanje k dokumentaciji je ena najbolj koristnih dejavnosti, saj pomagate drugim razumeti ogrodje.

Kako pisati?

Dokumentacija je namenjena predvsem ljudem, ki se s temo seznanjajo. Zato bi morala izpolnjevati nekaj pomembnih točk:

• Začnite s preprostim in splošnim. K naprednejšim temam preidite šele na koncu.
• Poskusite stvar čim bolje pojasniti. Poskusite na primer temo najprej pojasniti kolegu.
• Navajajte samo tiste informacije, ki jih uporabnik dejansko potrebuje vedeti o dani temi.
• Preverite, ali so vaše informacije resnično pravilne. Vsako kodo preizkusite.
• Bodite jedrnati – kar napišete, skrajšajte na polovico. In potem mirno še enkrat.
• Varčujte z vsemi vrstami poudarkov, od krepke pisave do okvirjev kot .[note].
• V kodah upoštevajte Standard kodiranja.

Osvojite tudi sintakso. Za predogled članka med pisanjem lahko uporabite urejevalnik s predogledom.

Jezikovne različice

Primarni jezik je angleščina, zato bi morale biti vaše spremembe najprej v angleščini. Če angleščina ni vaša močna stran, uporabite DeepL Translator in drugi vam bodo besedilo preverili.

Prevod v ostale jezike bo izveden samodejno po odobritvi in dodelavi vaše prilagoditve.

Manjše prilagoditve

Za prispevanje k dokumentaciji je nujno imeti račun na GitHub.

Najlažji način za manjšo spremembo v dokumentaciji je uporaba povezav na koncu vsake strani:

• Pokaži na GitHubu odpre izvorno obliko dane strani na GitHubu. Nato samo pritisnite gumb E in lahko začnete urejati (potrebno je biti prijavljen na GitHubu).
• Odpri predogled odpre urejevalnik, kjer takoj vidite tudi končno vizualno podobo.

Ker urejevalnik s predogledom nima možnosti shranjevanja sprememb neposredno na GitHub, je treba po končanem urejanju izvorni tekst kopirati v odložišče (z gumbom Copy to clipboard) in ga nato prilepiti v urejevalnik na GitHubu. Pod urejevalnim poljem je obrazec za pošiljanje. Tukaj ne pozabite na kratko povzeti in pojasniti razlog vaše prilagoditve. Po pošiljanju nastane t.i. pull request (PR), ki ga je mogoče nadalje urejati.

Večje prilagoditve

Primernejše kot uporaba vmesnika GitHub je biti seznanjen z osnovami dela z verzijskim sistemom Git. Če ne obvladate dela z Gitom, si lahko ogledate vodnik git – the simple guide in po potrebi uporabite katerega od mnogih grafičnih klientov.

Dokumentacijo urejajte na ta način:

1. na GitHubu si ustvarite fork repozitorija nette/docs
2. ta repozitorij klonirajte na svoj računalnik
3. nato v ustrezni veji izvedite spremembe
4. preverite odvečne presledke v besedilu z orodjem Code-Checker
5. spremembe shranite (commitnite)
6. če ste s spremembami zadovoljni, jih pošljite (pushnite) na GitHub v vaš fork
7. od tam jih pošljite v repozitorij nette/docs z ustvarjanjem pull requesta (PR)

Običajno je, da boste prejemali komentarje s pripombami. Spremljajte predlagane spremembe in jih vključite. Predlagane spremembe dodajte kot nove commite in ponovno pošljite na GitHub. Nikoli ne ustvarjajte novega pull requesta zaradi urejanja pull requesta.

Struktura dokumentacije

Celotna dokumentacija je nameščena na GitHubu v repozitoriju nette/docs. Trenutna različica je v veji master, starejše različice so nameščene v vejah kot doc-3.x, doc-2.x.

Vsebina vsake veje se deli na glavne mape, ki predstavljajo posamezna področja dokumentacije. Na primer application/ ustreza https://doc.nette.org/sl/application, latte/ ustreza https://latte.nette.org/sl itd. Vsaka ta mapa vsebuje podmape, ki predstavljajo jezikovne različice (sl, en, …) in po potrebi podmapo files s slikami, ki jih je mogoče vstavljati na strani v dokumentaciji.