Miről szól a referencia dokumentáció

Ezen útmutató segítségével megtanulhatod, hogy hogyan vehetsz részt az ubuntu dokumentációs csoport munkájában, hogyan kell kinéznie egy ubuntu.hu oldalon megjelenő hivatalos dokumentációnak, valamint hogy hogyan használhatod a bazaar verziókezelő rendszert a munka során. A dokumentum megmutatja, hogyan írhatsz hasonlóan egységes útmutatókat, mint amilyeneket a Rendszer → Segítség és támogatás menüpontban találhatsz, és hogyan tarthatod ezeket karban, a többiekkel együttműködve.

Hogyan kezdj bele

Telepítsd fel a python-docutils, a bzr és a bzr-gtk csomagokat:

sudo aptitude install python-docutils bzr bzr-gtk

Hogyan írj dokumentációt

Ebben a dokumentumban összegyűjtöttük a legfontosabb irányelveket, ajánlásokat és tudnivalókat a dokumentációkat, útmutatókat készítők számára. Kérjük, ezeket tartsd szem előtt, amikor dolgozol:

Törekedj az érthető fogalmazásra, és az egyértelmű terminológiára.

Figyelj oda a helyesírásra, nyelvhelyességre és az áttekinthető tördelésre.

Ahol lehet, használj magyar kifejezéseket - de nem mindenáron: ha a gyakorlatban az angol kifejezés terjedt el (például kernel) használd nyugodtan azt.

Mindig a magyar felhasználói felület kifejezéseid használd - kivéve, ahol ez értelemszerűen nem lehetséges (mert az adott alkalmazás nem érhető el magyar nyelven), vagy értelmetlen lenne (például arról írsz, hogy hogyan lehet egy angol rendszerre a magyar nyelvi támogatást telepíteni utólag).

Grafikus felületen a synaptic, konzolon az aptitude a preferált csomagkezelő, így a leírásokban is ezek szerepeljenek.

Az alapértelmezett disztribúció az Ubuntu. Vagyis hacsak nem kifejezetten Kubuntu vagy Xubuntu specifikus a téma, akkor mindig az Ubuntu-t vedd alapul, és erről készüljenek a képernyőképek is.

Grafikus alkalmazásokat grafikus csomagkezelővel (synaptic), konzolos alkalmazásokat konzolos csomagkezelővel (aptitude) telepítsd.

Külső forrásból származó csomagokat csak akkor használj, ha ez tényleg elkerülhetetlen (például ABEVJava).

Konzolos alkalmazásokat a

sudo

, grafikus alkalmazásokat a

gksu

(Ubuntu és Xubuntu esetében) vagy a

kdesudo

(Kubuntu esetében) paranccsal indítsd, ha rendszergazdai jogosultságot igényelnek. Vagyis

sudo nano ...

vagy

gksu gedit ...

, esetleg

kdesudo kate ...

- tehát például a

sudo gedit

forma kerülendő.

Ha fájlokat kell másolgatni a könyvtárstruktúra különböző helyeire, akkor azt konzolon, a megfelelően paraméterezett

cp

parancs segítségével tedd, hogy a felhasználónak csak be kelljen másolnia a megfelelő sorokat a konzolba.

Ha mellékelsz képeket, 320 pixel szélességig normál méretben, e felett nézőképként (hivatkozással a teljes méretű képre) helyezd el. Ha ez lehetséges, a nézőkép ne csak egyszerűen egy átméretezett kép legyen, hanem inkább kivágással emeld ki a fontos részt.

A képernyőképeket PNG, a fotókat JPEG formátumban töltsd fel.

Figyelj a licencekre és a jogszerűségre! Jelöld a felhasznált forrásokat, és ha más dokumentációjából használsz fel részleteket, akkor azt tedd jogszerűen: például a GNU-FDL (Free Documentation License) és a CC-by-sa licenc nem kompatibilis egymással. Vagyis ha az útmutatódban szerepelnek GNU-FDL alatt kiadott részletek, akkor az egész dokumentumot GNU-FDL licenc hatálya alá kell helyezni.

Alapesetben minden, az oldalra beküldött dokumentáció a Creative Commons Nevezd meg!-Így add tovább! 2.5 Magyarország Licenc alá kerül. Kérlek jelezd, ha ez valamilyen okból (például mert a felhasznált anyagok ezt nem teszik lehetővé) nem felel meg - és nevezd meg a dokumentum felhasználási feltételeit.

Az írásod úgy tudod a felhasználók számára is elérhetővé tenni, ha felveszed az index.rst fájlba. Figyelj oda, hogy a megfelelő szekcióba tedd, és igyekezz úgy elhelyezni a sorban, hogy a felhasználók számára a legáttekinthetőbb legyen.

Ha bizonytalan vagy valamivel kapcsolatban (például hogy miről írj, milyen megoldási utat válassz, hova helyezd el a dokumentumot) akkor kérdezz bátran a levelezőlistán - végül is ezért van.

A dokumentum feltöltésével nem ért véget véglegesen a munka. Kövesd nyomon az esetleges visszajelzéseket, hátha javítani kell rajta, vagy ki kell egészíteni, és egy új Ubuntu kiadás megjelenésekor aktualizáld, ha szükséges. Ha már nem szeretnéd karban tartani a dokumentumot, kérlek jelezd ezt az ubuntu-hu levelezési listán, hogy más át tudja venni tőled.

Mire figyelj a formázásnál

Egy sorba legfeljebb 80 karaktert írj. Ezt legegyszerűbben úgy tudod ellenőrizni, ha például Geditben bekapcsolod a jobb oldali margót. Nyugodtan használhatod a sortöréseket akár mondat közepén is, a renderelt oldalon ez nem fog látszódni. Természetesen a linkeket, felsorolásokat és egyéb hosszú egységeket nem kell megtörni.

Használd tudatosan és következetesen az alcímeket, hogy az egyes részek könnyen követhetőek, az útmutató pedig áttekinthető legyen. A főcímet egyenlőségjellel (=) húzd alá, az alcímeket kötőjellel (-).

A menüpontokat mindig dupla csillaggal jelöld, így a weboldalon **bold** karakterekkel fognak megjelenni. Például: **Rendszer → Segítség és támogatás**

Ha egy csomagról írsz, amit telepíteni kell, akkor annak a nevét tedd *csillagok* közé. Például: *python-docutils* csomag.

A konzolparancsokat az alábbi módon jelezd:

``sudo aptitude install python-docutils``

Egy kép néha többet mond ezer szónál - ezért természetesen képekkel is gazdagon illusztráld a mondandód. Persze ne feledkezz meg azokról sem, akik látási nehézségekkel küzdenek. Számukra mindig töltsd ki informatívan az alt taget:

A szövegben szereplő belső hivatkozások a dokumentum végén legyenek összegyűjtve, ezzel is áttekinthetőbbé téve. A hivatkozást úgy tudod jelölni, ha a szó végére egy alsó vonást teszel. Például: ubuntu.hu_

Ha több szavas linket szeretnél, tedd egy-egy balra dőlő aposztróf közé, valahogy így: `Nevezd meg!-Így add tovább! 2.5 Magyarország Licenc`_

Azt, hogy egy-egy link milyen külső oldalra mutasson, a szöveg végén tudod megadni. Például a fentebb említett ubuntu.hu link esetében ez így néz ki: ``.. _ubuntu.hu: http://ubuntu.hu``

A Nevezd meg!-Így add tovább! 2.5 Magyarország Licenc link esetében pedig a következőképpen: ``.. _Nevezd meg!-Így add tovább! 2.5 Magyarország Licenc: http://creativecommons.org/licenses/by-sa/2.5/hu/``

A dokumentáción belüli hivatkozásokat relatív módon, de a gyökérig visszalépve határozzuk meg, az alábbi példának megfelelően: ``.. _Ubuntu telepítése: ../../main/install/install-live.html``

Vagyis minden esetben a

../../

sorral kezdjük (ezzel gyakorlatilag visszalépünk két szintet, a branch gyökerébe), majd innen határozzuk meg az elérési utat:

main/install/install-live.html

. Mindig ezt a módszert kövessük, még akkor is, ha egy könyvtárban található a dokumentumunk azzal, amire hivatkozni szeretnénk, mert így később ha áthelyezzük az útmutatót, a hivatkozás ugyanúgy működni fog, és a "../../" string keresésével később könnyedén megtalálhatók a dokumentumon belüli belső hivatkozások. A fájlnév természetesen mindig ugyanaz lesz, mint az rst fájl neve, a kiterjesztés pedig .html lesz.

Természetesen használhatsz felsorolást is. A felsorolás lehet egyszerűen pontokba szedve:

Ezt akkor alkalmazd, ha egyszerűen csak fel szeretnél sorolni egymás mellé rendelt elemeket. Előfordulhat azonban az is, hogy egymást követő lépéseket szeretnél leírni. Ilyenkor sorszámozz:

A reStructuredText formátum szigorúan veszi a behúzásokat, sortöréseket, üres sorokat. Ezekre figyelj oda, mert emiatt is hibásan jelenhet meg a dokumentum.

Mielőtt feltöltenéd a módosított dokumentációt, teszteld le, hogy nincs-e benne hiba. Erre az

rst2html

nevű eszközt használhatod, ami a python-docutils csomag része. Ezt mindenképpen telepítsd fel:

sudo aptitude install python-docutils

Generáld le az rst fájlból a html fájlt:

rst2html doksi.rst doksi.html

Ha valamilyen formális hibát követtél el, erről hibaüzenet tájékoztat. A kész dokumentumot egy webböngészőben tudod leellenőrizni. Figyelj arra, hogy a html állományokat ne töltsd fel a branchbe. Ezt legegyszerűbben úgy teheted meg, ha a saját mappádban a .bazaar könyvtárban található ignore fájlba felveszed a html-t:

*.html

*.htm

A verziókövető rendszer használata

Telepítsd fel a bazaar verziókövető rendszert, ha még nem tetted meg korábban:

sudo aptitude install bzr

Ha grafikus eszközt is szeretnénk, telepítsd a bzr-gtk csomagot is:

sudo aptitude install bzr-gtk

Ezután hozd létre konzolban a felhasználót:

bzr whoami "Példa Péter <pelda.peter@gmail.com>"

Majd ellenőrizd le:

bzr whoami

Regisztrálj a Launchpadon, ha még korábban ezt nem tetted meg. A Launchpad a Canonical koordinációs oldala, ami abban nyújt segítséget, hogy a szabad szoftveres projektek aktivistái együtt tudjanak működni. Ha szeretnél részt venni a dokumentációs csapat munkájában, kérd felvételed az ubuntu-hu-doc, vagyis a Magyar Ubuntu Közösség dokumentációs csoportjába.

Ezután hozz létre egy ssh publikus kulcsot magadnak (ha még nem lenne), és töltsd fel a Launchpadra. A kulcsot az Alkalmazások → Kellékek → Jelszavak és titkosítási kulcsok alkalmazással tudod legegyszerűbben elkészíteni. Itt válasszuk a Fájl → Új menüpontot. Ezen belül az válaszd az SSH kulcs pontot. Add meg a kulcsleírást, majd kattints a Csak létrehozás gombra. Add meg a jelmondatot, ami a kulcsodat védeni fogja.

Ezzel létrejön a kulcs a saját mappádban a .ssh alatt. Ez két fájlból áll: az id_rsa a privát kulcs, az id_rsa.pub pedig a publikus kulcs. Ezután töltsd fel a publikus kulcsod (id_rsa.pub) a launchpadra: https://launchpad.net/people/+me/+editsshkeys

Másold be a publikus kulcsod (az id_rsa.pub fájl tartalmát) a szövegdobozba és klikkelj az Import public key gombra. Így már le tudod tölteni a launchpadról a projektet a saját gépedre. Elsőként a gyakorló branchet töltsd le: ez nem kerül ki a weboldalra, így nyugodtan tudsz rajta gyakorolni, kísérletezni. Hozz létre egy könyvtárat, ahol a projektet szeretnéd tárolni, majd tükrözd le:

bzr checkout bzr+ssh://launchpadazonosító@bazaar.launchpad.net/~ubuntu-hu-doc/ubuntu-hu-doc/rookie

Ezt követően máris megtalálhatod a gépeden a projekt fájljait, és munkához láthatsz. Ha már korábban letükrözted a projektet, akkor mielőtt munkához látnál, mindenképpen aktualizáld. Ehhez lépj az adott branchet tartalmazó könyvtárba és ott add ki az alábbi parancsot:

bzr update

Ha elvégezted a változatásaidat, és eközben új fájlok keletkeztek, add hozzá ezeket a projekthez:

bzr add <fájlnév>

Majd commitolj:

bzr commit -m "változtatások összefoglalása"

Ez utóbbi két parancs is azt feltételezi, hogy az adott branch könyvtárában tartózkodsz. A "változtatások összefoglalása" pedig néhány szavas leírása annak, amit tettél: "link frissítése" vagy "gépelési hibák javítása" stb. Ezzel fel is kerülnek a Launchpadra a változtatások. A rendszer minden óra 50 perckor frissít és egészkor kerülnek ki láthatóan a változások. Figyelj oda arra, hogy ha ilyenkor bent marad egy hiba, akkor azt csak egy óra múlva, a következő szinkronizálással lehet javítani.

Hogyan épül fel a könyvtárstruktúra

Az egyes kiadásokhoz készült útmutatók külön-külön branchben találhatók. A branchek neve a kiadások kódnevére utal, vagyis az Ubuntu 8.04-hez (Hardy Heron) készült dokumentációk egy hardy, az Ubuntu 8.10-hez (Intrepid Ibex) készültek egy intrepid, míg az Ubuntu 9.04-hez (Jaunty Jackalope) készültek egy jaunty nevű könyvtárban kapnak helyet.

A könyvtárakon belül két alkönyvtár található: main és universe

A main könyvtárban találhatók azok az útmutatók, amelyeket folyamatosan karban tart a dokumentációs csoport, és kiadásról kiadásra aktualizál.

A universe könyvtárban találhatók azok az útmutatók, amelyeket egyszer alaposan átnézett és kijavított a dokumentációs csoport, azonban nincs kapacitása kiadásról kiadásra ellenőrizni és aktualizálni. Ezek frissítése a rendelkező idő és kapacitás függvényében történik.

A dokumentumokhoz tartozó rst állományok ezen két könyvtár valamelyikében kapnak helyet. Például: main/install.rst

A dokumentumhoz tartozó fotók és képernyőképek egy img/dokumentum alkönyvtárba kerülnek, például: main/img/install/install-live-hardy.png

Figyelj arra, hogy a fájlnevek rövidek, tömörek és egyértelműek legyenek.

Az egyes kiadások dokumentációját tartalmazó branchek mellett van még egy, rookie nevet viselő is: ez nem kerül ki a weboldalra, és kifejezetten a gyakorlást, próbálkozást szolgálja. Amikor először ismerkedsz a verziókövető rendszer és az rst működésével, ezen gyakorolj, hogy ha esetlegesen elrontanál valamit, az ne érintse a nyilvános dokumentációt.

Hibák jelentése és követése

Természetesen, mint mindenben, így a közösségi dokumentációban is lehetnek hibák. Ezek bejelentésére, koordinálására szintén a Launchpad szolgál. A projekt hibabejelentő oldala a https://bugs.launchpad.net/ubuntu-hu-doc címen érhető el.

A dokumentációs csoport egyik legfontosabb feladata a dokumentációk létrehozása mellett a hibák nyomon követése és javítása. Ebben a legfontosabb segítség a Launchpad. A dokumentációs csoport tagjai itt tudják nyomon követni, hogy milyen ismert hibák vannak az útmutatókban, és ennek segítségével tudják javítani.

Az új hibákat ezen az oldalon találod: https://bugs.launchpad.net/ubuntu-hu-doc/+bugs?search=Search&field.status=New

Ha egy hiba javítását szeretnéd elvállalni, azt az Assigned to legördülő menüponttal tudod megtenni: az Assigned to pont alatt válaszd a Me opciót, így mindenki láthatja, hogy te foglalkozol vele.

Az Importance pont alatt tudod megadni a hiba fontosságát: Ennek különösen akkor van nagy jelentősége, amikor egy új kiadás dokumentációja készül, hiszen ilyenkor jelentősen megszaporodnak a bugreportok.

A Status pont alatt tudod megadni a bug helyzetét. A New azt jelenti, hogy új hibáról van szó, az Incomplete azt, hogy a hibajelentés hiányos, az Invalid azt, hogy nem megfelelő vagy nem értelmezhető, a Won't Fix azt, hogy a hibát valamilyen okból nem fogjuk javítani (például azért, mert nem is hiba). A Confirmed azt, hogy a hiba megerősített, a Triaged azt, hogy a hiba reprodukálható (ez dokumentáció esetében nem szükséges), az In Progress azt, hogy a hiba javítás alatt áll, a Fix Committed azt jelenti, hogy a javítás már a bazaarban van, míg a Fix Released azt jelenti, hogy a javítás kikerült az oldalra.

Fontos, hogy ha javítottál egy bejelentett hibát, akkor azt itt is jelezd, és zárd le a nyitott bugreportot.

Erről az útmutatóról

Ez az útmutató jelenleg még készítés alatt áll. Még hiányozhatnak belőle olyan fontos dolgok, amelyek a hatékony és eredményes munka előfeltételei lehetnek. Éppen ezért, ha bármiben bizonytalan lennél, akkor kérdezz bátran. A kérdéseid és a menet közben szerzett tapasztalatok függvényében bővül folyamatosan majd ez az útmutató is.