Hogyan járuljunk hozzá a dokumentációhoz

A dokumentációhoz való hozzájárulás az egyik leghasznosabb tevékenység, mivel segít másoknak megérteni a keretrendszert.

Hogyan írjunk?

A dokumentáció elsősorban azoknak szól, akik most ismerkednek a témával. Ezért több fontos pontnak kell megfelelnie:

• Kezdje az egyszerűtől és általánostól. Csak a végén térjen át a haladóbb témákra.
• Próbálja meg a lehető legjobban elmagyarázni a dolgot. Például próbálja meg először elmagyarázni a témát egy kollégának.
• Csak azokat az információkat közölje, amelyekre a felhasználónak valóban szüksége van az adott témához.
• Ellenőrizze, hogy az információi valóban igazak-e. Minden kódot teszteljen le.
• Legyen tömör – amit ír, rövidítse le a felére. Aztán nyugodtan még egyszer.
• Takarékoskodjon mindenféle kiemeléssel, a félkövér betűktől az olyan keretekig, mint a .[note].
• A kódokban tartsa be a kódolási szabványt.

Sajátítsa el a szintaxist is. A cikk írása közbeni előnézethez használhatja az előnézeti szerkesztőt.

Nyelvi változatok

Az elsődleges nyelv az angol, tehát a változtatásainak csehül és angolul is meg kell lenniük. Ha az angol nem az erőssége, használja a DeepL Translator-t, és a többiek ellenőrzik a szövegét.

A többi nyelvre történő fordítás automatikusan megtörténik a módosítás jóváhagyása és finomítása után.

Apróbb módosítások

A dokumentációhoz való hozzájáruláshoz elengedhetetlen egy GitHub fiók.

A legegyszerűbb módja egy apróbb változtatás végrehajtásának a dokumentációban az, ha kihasználja az egyes oldalak végén található linkeket:

• Megjelenítés GitHubon megnyitja az adott oldal forráskódját a GitHubon. Ezután elég megnyomni az E gombot, és elkezdheti a szerkesztést (szükséges bejelentkezni a GitHubra).
• Előnézet megnyitása megnyitja a szerkesztőt, ahol rögtön láthatja a végső vizuális megjelenést is.

Mivel az előnézeti szerkesztő nem tudja közvetlenül a GitHubra menteni a változtatásokat, a módosítások befejezése után a forrásszöveget a vágólapra kell másolni (a Copy to clipboard gombbal), majd beilleszteni a GitHub szerkesztőjébe. A szerkesztőmező alatt található az elküldési űrlap. Itt ne felejtse el röviden összefoglalni és elmagyarázni a módosítás okát. Az elküldés után létrejön egy úgynevezett pull request (PR), amelyet tovább lehet szerkeszteni.

Nagyobb módosítások

A GitHub felületének használata helyett célszerűbb tisztában lenni a Git verziókezelő rendszer alapjaival. Ha nem ismeri a Git használatát, megnézheti a git – the simple guide útmutatót, és esetleg használhatja a számos grafikus kliens egyikét.

A dokumentációt a következő módon szerkessze:

1. a GitHubon hozzon létre egy forkot a nette/docs repository-ból
2. ezt a repository-t klónozza a számítógépére
3. ezután a megfelelő ágban végezze el a változtatásokat
4. ellenőrizze a felesleges szóközöket a szövegben a Code-Checker eszközzel
5. mentse el a változtatásokat (commitolja)
6. ha elégedett a változtatásokkal, küldje el (pusholja) őket a GitHubra a saját forkjába
7. onnan küldje el őket a nette/docs repository-ba egy pull request (PR) létrehozásával

Gyakori, hogy észrevételeket tartalmazó kommenteket fog kapni. Kövesse nyomon a javasolt változtatásokat, és építse be őket. A javasolt változtatásokat adja hozzá új commitokként, és küldje el újra a GitHubra. Soha ne hozzon létre új pull requestet egy pull request módosítása miatt.

Dokumentáció struktúrája

Az egész dokumentáció a GitHubon található a nette/docs repository-ban. Az aktuális verzió a master ágban van, a régebbi verziók olyan ágakban találhatók, mint a doc-3.x, doc-2.x.

Minden ág tartalma fő mappákra oszlik, amelyek a dokumentáció egyes területeit képviselik. Például az application/ megfelel a https://doc.nette.org/hu/application címnek, a latte/ megfelel a https://latte.nette.org címnek stb. Minden ilyen mappa tartalmaz almappákat, amelyek a nyelvi változatokat (hu, en, …) képviselik, és esetleg egy files almappát képekkel, amelyeket be lehet illeszteni a dokumentáció oldalaira.