Hogyan készíts egy jó leírást?
 
Bevezetõ
Újra és újra látok igénytelenül elkészített leírásokat és útmutatókat ezen a fórumon, de ennek a leckének a megírásával szeretnék ezen változtatni.
Ezzel nem akarok senkit sem elrettenteni egy útmutató megírásától, csak megpróbálom elmagyarázni, hogy hogyan is kellene csinálni.
Problémák
 

• 
  Tapasztalat

Ha egy útmutatót írsz, akkor az emberek feltételezni fogják, hogy tudod is, hogy mirõl írsz - De miért írnál olyan témáról, amit még te sem ismersz? Ha valamit egy másik módon csinálsz, akkor nagyon ritkán fogják kielemezni, hogy melyik módszer is a jobb, egyszerûen csak elfogadják, hogy az általad leírt mód a legjobb megoldás, mivel ez egy leírásban van!
Tehát ha egy leckét írsz, akkor erõsen azt sugallod, hogy jártas vagy a témában, és elég tapasztalt, hogy írj róla.
 

• 
  A topik használata

Egy topikban az emberek kérdéseket tesznek fel, ha megoldást kínálsz egy problémára, akkor mások is úgy gondolhatják, hogy van rá jobb módjuk, ezért õk is leírják sajátjaikat, nem számít, hogy melyik a jobb - a beszélgetés jelen van.
Egy leírást olvasva az emberek feltételezik, hogy a te módszered helyes, hiszen nem nyitnál azért topikot, hogy rosszra tanítsd õket( nos, néhányan csinálják, de ezt szeretném megállítani ). Nagyon kevesen fognak igazából az olvasmányodban található információkról kérdezõsködni.
 

• 
  Haladás a korral

Ennek a közösségnek egy hatalmas problémája a rossz módszerek terjesztése. Vegyünk két gyakori példát - 256 és strtok. A SA:MP szkripting hajnalán ezek jól mûködõ, és elfogadható módszerek voltak, elvégezték feladataikat, és az emberek nem tudtak ezeknél jobb megoldásokat. Az idõ múlásával az emberek egyre hatékonyabb módszereket dolgoztak ki( névszerint zcmd/sscanf, kisebb tömbök, stb ), tehát a régi módszereket el kell felejtenünk, igaz? Nem!
Mivel az emberek még mindig használták ezeket a régebbi módszereket a forráskódjukban( a fejlesztés sok munka lehet, tehát ezt vélték helyes útnak ), az új szkriptereket ugyanúgy ezekre a módszerekre tanították, akik aztán másoknak tanították meg ezeket. De ha tudod, hogy valaminek nem a legújabb változatát használod, akkor MIÉRT SZÓLSZ HOZZÁ? Inkább magyarázd el a jobb megoldást, vagy mondd el, miért kéne/nem kéne használni az adott módszert, de a legjobban teszed, ha nem írsz választ.
 

• 
  Számonkérés

Ha venném a fáradtságot, és elolvasnám az összes eddigi megírt útmutatót, és valamit helytelennek találnék, akkor számon kérném a témaindítót. Ha írsz egy leírást, akkor azzal azt hangsúlyozod, hogy tudsz valamit, de ha valaki be tudja bizonyítani, hogy NEM tudod, akkor nem is kellett volna megnyitnod azt a topikot. Nagyon kevés ember kéri számon a témaindítót az útmutatóknál, ez kár, bárcsak az emberek ezt tennék velem az én leírásaimnál!
Utánajárás
Úgy tûnik ez nagyon hiányzik a legtöbb leírásból - ha arra készülsz, hogy elmondd valakinek, hogy hogyan csináljon valamit, akkor az ELSÕ dolog amit meg kellene kérdezned magadtól, hogy TE a lehetõ legjobban csinálod-e? Csak mert valamit már évek óta csinálsz, és eddig mûködött, az még nem jelenti azt is, hogy jó.
Ha egy függvényt akarsz bemutatni - tekintsd át, vedd szemügyre, nézd meg, hogy vannak-e alternatív megoldásai is. Ha sokrétû az, amit be szeretnél mutatni, akkor vedd figyelembe, hogy melyik használja a legtöbb idõt, vagy a legtöbb kelléket, stb. Ez azt is eredményezheti, hogy át kell alakítanod a leírásodat, és akkor mi van? Ez azt jelenti, hogy más emberek megtanulhatnak egy jobb módszert, ami az igazi lényege egy útmutató megírásának.
Magyarázatok
Az olyan leírások, amik annyiból állnak, hogy \"csináld ezt meg ezt, aztán ezt és kész\" értelmetlenek. Néhány ember lehet csak ilyen lépésrõl-lépésre instrukciókat akar, de a legtöbben szeretnék megérteni, hogy MIÉRT is kell ezt így csinálni. Írd meg a lépésrõl-lépésre leckét, tedd a leírás tetejére, de utána lentebb magyarázz meg mindent. Akármelyik szkripter ha valaha is jóvá szeretne válni, el fogja olvasni, és meg fogja érteni, hogy MIÉRT kell azt csinálni, és nem csak tudni fogja, hogy MIT kell csinálni.
Prezentálás
Ez elég fontos, habár nem az erõsségem, így nem fogok sokat írni.
Csak gyõzõdj meg róla, hogy elegáns-e, és rendezd kisebb szekciókba ha lehetséges. Észrevettem, hogy ez egy szövegen alapuló leírás, szóval ez nem a legjobb példa erre, de próbáld meg elválasztani a szövegrészeket kódbeszúrásokkal( CODE tagek ).  Az emberek nem szeretik a nagy, ömlesztett szövegeket.
Az, hogy HOVÁ írod az útmutatód, szintén meghatározó. Én 99.9%-ban a Leírások fórumrészt mondanám, de attól függ, hogy mi a témád. Például ha egy játékmódról/filterszkriptrõl, vagy egy függvénykönyvtárról írsz, akkor tedd annak a témájába - hiszen ismered a szabályokat a publikálással kapcsolatban!
Egy bevezetés és egy következtetés( vagy befejezés ) szintén hasznos lehet.
Téves információk közlése
Újra ki szeretném emelni ezt a pontot - gyõzõdj meg róla, hogy amit írsz, az összhangban van a jelenlegi módszerekkel. Ha például parancs is szerepel az útmutatódban, használj zcmd-t( vagy hasonlót ), ha tömböket használsz, találd ki, milyen méretûek kell legyenek, stb.
És gyõzõdj meg arról is, hogy amit állítasz, az olyan jó, amilyen csak lehet. Természetesen késõbb ráférhet némi felújítás, de ne használj idejétmúlt módszereket.
Következtetés
Járj utána a cikked témáinak, és emlékezz, hogy ha helytelen információt teszel közzé, én - és remélhetõleg ezentúl mások is - számon fogunk érte kérni, és idiótának fogsz tûnni.

---

Az eredeti leírást Y_Less készítette, a témát elérheted itt. Azért fordítottam le, és tettem ki ide, mert úgy gondolom, hogy ezen a fórumon is jelen van ez a probléma.