Egy hálózat monitorozó és nyilvántartó rendszer mégegyszer

Már volt szerencsém erről a lassan, de bizonytalanul készülő rendszerről írni : http://hup.hu/node/109290 és http://hup.hu/node/109293 . A "nagy" érdeklődés, és a sok "pozitív" kritika ellenére még nem kukáztam a projectet.
El ugyan még nem készült, de kigyomláltam a nem publikus részeket és ami elkészült, azt kipakoltam a GitHub-ra : https://github.com/csikfer/lanview2 .
Sajnos a dokumentáció írása nem az erősségem, de azért megpróbáltam kiizzadni egy dokumentációnak tűnő valamit (lv2.odt), még azért dolgozom rajta.
Kiegészítés : A dokumentáció (szerűség) html-ben : http://svn.kkfk.bgf.hu/lanview2.doc/lv2.html folyamatosan frissül.

Hozzászólások

"typus" ssszz.... tipus vagy type. Typus nincs.
--

Ki oda vagyik, hol szall a galamb, elszalasztja a kincset itt alant. 

Megnyugtatlak van benne ennél több helyesírási hiba, sőt program hiba is. És bizonyára hihetetlen, de a hibák nem direkt kerültek bele, és még csak azt sem tesztelem, hogy a nyelvnácik figyelnek-e. Ez az egész még nincs készen, nincs letisztázva, vagy lektorálva. Annak nagyon örülök, ha valaki segít, mert igencsak elkelne, de hogy Te mi a frászt akartál az nem világos.
Persze akiket irritálnak a hasonló nyelvi fordulatok, attól elnézést kérek, sajnos csak egy ember vagyok, és nem kicsit feszített tempóban készül az egész. Néha én is meglepődöm miket írtam, amikor visszaolvasom.
ui.: Javítottam.

odt doksi behanyva gitbe, broaf. igenyesseg rulez...

Jó szándékú, segítőkész, és nem utolsó sorban empatikus "kollégák" a tőlük megszokott igen igényes hozzászólása az még ennél is rulez-ebb.

Tisztelettel megkérném azokat a HUP olvasókat, akik ide tévednek, és nemérdeki őket a téma, vagy nincs hozzá kedvük, azok hozzászólás nélkül legyenek szívesek távozni, és ne a téma szét offolásával próbálják meg növelni a kívánatosnál alacsonyabb endorfin szintjüket.
Előre is köszönöm.

ui.: Ha esetleg valamit félre értettem, és csak az odf a git-ben dolog rettent vissza. Milyen formátumban kéred és hova? Nekem így egyszerűnek tűnt, és azt hittem nem olyan rettenet, még ha nem is egy jó megoldás.

Nem akarlak bokdosni, jo szandekuan irom, hogy van abban valami, amit mond. Egy kod dokumentalasat mindig plaintext fajlban csinaljuk, mert ahhoz nem kell semmilyen eszkoz az olvasashoz. A GitHub egy kivalo eszkozt ad a kezedbe, a Markdown formatumot, tessek azt hasznalni, es akkor mindenki boldog lesz, aki hozza akar jarulni a kododhoz. Az odt-t nem lehet elolvasni, csak specialis eszkozzel.
--

Ki oda vagyik, hol szall a galamb, elszalasztja a kincset itt alant. 

"Egy kod dokumentalasat mindig plaintext fajlban csinaljuk"

Ez akkora bullshit, hogy erre még NagyZ sem tudna elég nagy sértést idevágni...

Arról nem is beszélve, hogy nem a kódot kell dokumentálni, hanem a projekt egészét, ami ott kezdődik, hogy funkcionális specifikáció és akkor még szó nem volt arról, hogy egyáltalán milyen eszközt választasz a megvalósításhoz. Nemhogy kód...

----------------
Lvl86 Troll, "hobbifejlesztő" - Think Wishfully™

Oke, mi szol a plaintext ellen? Most nem azt mondtam, hogy nem lehet peldaul LaTeXben, vagy Markdownban, de _szerintem_ egy plaintext dokumentaciot akkor is el tudsz olvasni, ha epp nincs nalad semmi, mig peldaul egy gyoyoruen formazot .docx-et vagy .odt-t csak a megfelelo eszkozzel tudsz elolvasni, nem is beszelve az inkompatibilitasok hosszu es kellemetlen sorarol, amikor a szepen felepitett odt osszeomlik az Office-s importer sulya alatt, vagy ugyanez docx es LibreOffice viszonylatban.

Nekem legalabbis az a tapasztalatom, hogy ha valami plaintext formatumban (LaTeX, Markdown, RDoc, de legrosszabb esetben HTML) van egy dokumentacio, akkor sokkal kenyelmesebben tudok benne keresni, mintha valami felbinaris szornyeteget kell abszolvalni. Es ezekhez millioegy eszkoz elerheto, sokkal jobban is illeszkednek akarmilyen kornyezetbe, mint barmilyen mas formatum.

Persze, a grafikonok, folyamatabrak legyenek png-ben, de azert egy specifikaciot nehogy mar ne lehessen elolvasni konzolos eszkozokkel.
--

Ki oda vagyik, hol szall a galamb, elszalasztja a kincset itt alant. 

Az szól ellene, hogy külsőségeken picsogás, ahelyett, hogy minél gyorsabban a célra törekednél.

Az ábrák legyenek png-k... Mondj már egy nyomorék érvet mellette... Egyrészt se magyarázat hozzá (anélkül szart se ér) másrészt kurva nehéz szerkeszteni (főleg folyamatokat, ahol összenyilazott dobozkákat rendezget az ember), harmadrészt mégis hogy adsz egy ilyen "dokumentációt" oda mondjuk egy ügyfélnek? Szokásod szerint elvesztés a célt magad elől és tolod a maszlagot.

Készítettél-e már egyáltalán olyan (funkcionális) specifikációt, ami alapján mondjuk szerződés született egy ügyféllel?

A képtelen vagy gondoskodni arrol, hogy a szukseges eszközök nálad legyenek érv külön rossz... Legyen nálad, ha kell. (És egyebkent is, odt, docx belul XML, az meg plaintext :)

----------------
[=8]Lvl86 Troll, "hobbifejlesztő" - Think Wishfully™[/size

Nem tudom, szerintem egy dokumentacional pont olyan fontos a kulso igenyesseg, mint a beltartalom.

A PNG-t nem szerkeszteni kell, hanem exportalni. Tippre biztosan valami UML vagy hasonlo diagramm editorral dolgozol, es szinte biztos vagyok benne, hogy kepes valami raszteres formaba lementeni/kiexportalni a munkadat. Persze, ehhez mar egy csoppet gondolkodni is kell.

Az ugyfel szamara lehet kesziteni peldaul PDF-et, de ha odaadsz egy HTML fajlt kepekkel, azt a legtobb szerkeszto ugyanolyan jol meg tudja nyitni (peldaul a Word is, a LibreOffice ilyen iranyu kepessegeirol nincs tudomasom).

Specifikaciot pont nem, de egyebkent rengeteg dokumentaciot irok plaintextben, es jol mukodik. Barki barmikor barhonnan meg tudja tekinteni, szinte barmilyen eszkozzel. Ha nagyon csillivillinek kell lennie, akkor megcsinalom latexben, abbol PDF-tol DOC-ig barmibe tudok exportalni.
--

Ki oda vagyik, hol szall a galamb, elszalasztja a kincset itt alant. 

Igen, fontos, hogy kinézzen valahogy. (Plain text meg aztán marhára ki tud nézni valahogy...)

"kepes valami raszteres formaba lementeni/kiexportalni a munkadat"

Úgy van, használjak 123 különböző programot...

"UML"

Láthatóan nem fogtad fel, miről van szó. Képernyőtervekről ákom-bákom ábrákat nem fogsz te készíteni UML-ben.

"Specifikaciot pont nem"

Akkor talán nem kellene ökörségeket benyögni.

"kiexportálom"

Mert ugye olyan jó, hogy Wordben egész kulturáltan lehet megjegyzéseket fűzni a lap szépére, amit utána egy kattintással le lehet tisztítani, addig plain/textben ömlesztve van minden szar. Ügyfél meg nem fog neked LaTeX-el szopkodni, csak hogy "jól nézzen ki".

----------------
Lvl86 Troll, "hobbifejlesztő" - Think Wishfully™

"Képernyőtervekről ákom-bákom ábrákat" azt nem rajzprogramban szokas? Vagy papiron es bescannelve? Mindkettobol nagyon konnyu egy raszteres cuccot kiexportalni.

Eszemben sincs, hogy hasznalj 123 programot, egyet kell hasznalni, de az legyen jo.

Az ugyfelnek - mint irtam is - altalaban PDF-et, HTML-t vagy legrosszabb esetben DOC-ot kuldok, mert ezej latexbol egy mozdulattal eloallithatoak, a jobb latex szerkesztokben meg csak egy gombnyomas. Meglepo modon az Acrobat Reader nagyon jol tud megjegyzeseket hozzaadni a dokumentumhoz. De latexbol lehet csinalni word dokumentumot is, amibe a word szinten tud megjegyzeseket fuzni. De ha nem olvasod el a mondataimat, akkor kar is vitatkoznunk.
--

Ki oda vagyik, hol szall a galamb, elszalasztja a kincset itt alant. 

Nem az a probléma, hogy a kritika nem jogos.
NagyZ minden bizonnyal egy intelligens ember, mármint az IQ-ja alapján. Ugyanakkor a stílusa (amivel sajnos nincs egyedül) az minősíthetetlen, ezekből a kritikákból süt a rosszindulat és a gyűlölet. Szinte mindig az a konklúziója, hogy mind kritizált munka mind az elkövető egy hulladék. És arra sem igen emlékszem, hogy ezen kinyilatkozások közé valaha is belekeveredett volna bármilyen javaslat, a hiba elkerülésére (már azon kívül, hogy az elkövető Taigetosz pozitív és, ha már elmulasztották lehajítani, ugorhatna önszántából).
És nem, nem vagyok sértődékeny. Egyszerűen számomra érthetetlen ez a mentalitás, és ha nem értek valamit, akkor hajlamos vagyok a dolgon hosszasan (és feleslegesen) jojózni.

És visszatérve a kritika jogosságára. Ha itt most vita alakult ki arról, hogy akkor hogyan is kéne dokumentálni, akkor nem is biztos, hogy akkora böszmeséget követtem el, ha a nagy kritikusok sem értenek egyet.

És ugyan nekem is ellenérzésem volt és van is az ODF dokumentáció miatt, de marad így. Ha valaki meg akarja nézni, az meg tudja. Én meg egyszerűen nem vagyok hajlandó még további erőn felüli erőfeszítésekre, csak azért, hogy ne legyen mibe belekötni azoknak, akiket ez az egész nem is érdekel, csak végre fikázhatnak valamit, vagy egy módszertani értekezéssel fitogtassák a szaktudásukat.

Valószínűleg felesleges volt ezt az egészet ide kitenni, és előbb vagy utóbb a GitHub-ról is törlöm, és marad hobbi projekt. Ha egyszer véletlenül elkészül akkor majd meggondolom mit kezdek vele.

Doksihoz javaslatok. Bár ennek nagy része átcsap egy tervezési módszertanba is:

- Tegyél bele tartalomjegyzéket.
- Legyen rendes verziózás benne, dátumozva, hogy mit módosítottál, ha valamit véglegesnek nyilvánítottál.
- Elején fél-egy oldalban foglald össze a projekt céljait, lehetőleg felsorolásos formában.
- Utána tegyél bele fogalomtárat, kiváltképp az általad megalkotott fogalmakat jelöld benne, hogy te min mit értesz.
- Készíts ábrát, hogy milyen környezetre/konfigurációra lett tervezve a szoftver (nem muszáj UML deployment diagram, de az se rossz)
- Use-case-ket, folyamatokat, vedd sorra valami rendezettebb formában. (Előny, ha a folyamatokat ábrákkal tarkítőd.)
- Ezután ebből készíts egy funkcionális specifikációt, hogy mit hogyan kellene tudnia a szoftverednek. Előny, ha képernyőnként végigmész, mindenhez csinálsz egy vázlatot és leírod, hogy mi mit csinál. Erre bőven jó a Word (vagy kedvenc szövegszerkesztőd) beépített szövegdobozai is, de lehet használni valami erre a célra készített szoftvert. (Mikor előző munkahelyemen megrendelőkkel kellett egyeztetni az ilyen ábrák és leírások nagyon nem keveset segített a megrendelőnek.)
- Ha vannak általános UI koncepciók azt is írd bele.
- Készíts ábrát a szoftvered belső architektúrájáról. (Szép kis dobozokból felépítve, nem muszáj UML)
- Írd le, hogy hol mi merre hány méter, modulokat fejtsd ki részletesebben, stb.
- A Doxigen NEM dokumentáció. Az csak sallang.
- Természetesen minden ábrához szöveges leírás.
- Azelőtt készítsd el, mielőtt elkezdenéd megvalósítani. :)

Ez se lesz így teljesen szép, mert félig funkcionális, félig műszaki spec. de legalább nagyjából benne van minden.

És igen, így lehet, hogy sokkal-sokkal több időt el fog venni a dokumentáció megírása, de meg lesz tervezve a szoftvered és tényleg csak le kell kódolnod azt. Előző munkahelyemen volt egy kb. 3 hónapos projekt (2-3 fejlesztő + grafikus), azzal, hogy egy ilyen doksit összehoztam, önmagában elment nekem 3 hét legalább, de utána a kódolási munkák pikk-pakk megvoltak, időre lehetett szállítani.

----------------
Lvl86 Troll, "hobbifejlesztő" - Think Wishfully™

A fentebb megjelent kifakadásomat még véletlenül se vedd magadra, mert nem neked, és főleg nem a fenti hozzászólásodnak szólt.
A javaslatok ugyan jók, de én ehhez egyedül nem érzem magam elegendőnek.
Marad a fenti konklúzió, elhobbizgatok úgy ahogy eddig, aztán majd meglátjuk.
Ebbe valószínűleg csak olyan ember szállna be, aki hasonló állatfaj mint én, programozó is meg rendszergazda is egyszerre, és olyan helyen rendszergazda, ahol hasonló feladatok vannak mint az én munkahelyemen. Tartok tőle, hogy nem sok ilyen van.

Van terv. Csak nincs megfelelő ill. fogyasztható formába öntve, és sajnos egy része kidolgozva sem.
Ráadásul ennek van egy PHP-ben megírt régebbi változata, ami nagyon jól használható volt, amíg volt időm a karbantartására, és szét nem hullott. A régihez valóban nem volt semmilyen "terv", az úgy kialakult, ha kellett valami akkor megcsináltam hozzá, és voltak benne olyan funkciók is, amire menet közben csodálkoztam rá, hogy "jé erre is jó". Egy évekig használt rendszer szerintem nagyon jó vezérfonal, az erényeivel és a hibáival együtt, csak arról nincs fogalmam, hogy ebből hogyan kéne fogyasztható dokumentációt csinálni.
Nem adtam fel NagyZ miatt. Csak nagyon úgy tűnik az az álmom, hogy ez egy közösségi projekté növi ki magát, az teljesen reménytelen. Ehhez több dolog kell: egyik az, hogy valóban értéket képviseljen amit kitaláltam ill. eddig csináltam. Ezt ugye én érdemben nem tudom eldönteni, mert elfogult vagyok. A másik, hogy megfelelő dokumentációval, és egy kis önreklámmal esélyt kell adni, hogy ezt az értéket felismerjék. Ez utóbbiban biztos nem vagyok jó (és mielőtt valaki beleköt: igen tudom, még az sem derült ki, hogy érték).

a dokumentacios lepesnel tartunk, ami eddig hianyzik. ha kozosseget akarsz hozza, akkor az elso lepes az, hogy nulla erofeszites legyen megneznem hogy mi a franc az a program _egyaltalan_, nem az, hogy a fajlok kozott turok egy odfet.

HA lenne wiki, meg meg is neznem mit csinal a programod. de nincs.

Az ODT-ket kikonvertáltam HTML-be : http://svn.kkfk.bgf.hu/lanview2.doc/lv2.html
Egyenlőre nem sikerült kitalálni, hogy a meglévőkből hogyan lesz wiki, vagy más GitHub által támogatott formátum.

"a dokumentacios lepesnel tartunk, ami eddig hianyzik"

Igen, ott tartunk. Ez a projekt kettős céllal indult, egyrészt ez nekem szórakozás, az itt eddig nem említett (mert azt valaki finanszírozta, így nem "szabad") hw fejlesztésekkel együtt. Másrészt (mivel egy elég nagy rendszer hálózati rendszergazdája vagyok) nagyon hasznos lenne a munkámhoz. Mivel gyakorlatilag (egy GUI modul kivételével) ezt az egészet egyedül csinálom semmi szükség nem volt bőrbe kötött dokumentációkra. Ez nem jelenti azt hogy nincs, de eddig nem volt cél a közérthetőség (az önreklám meg aztán végkép nem), csak annyi, hogy ne merüljön feledésbe, amit eddig kitaláltam, és 30 ezer programsort (ami később csak több lesz) nem nagyon lehet átlátni máshogy, csak ha tele van megjegyzésekkel (amiből aztán egyesek szerint dokumentációnak látszó sallangot lehet generálni a doxygen-nel). Jelenleg sem arról van szó, hogy én ezt a projektet nem tudnám befejezni. A baj ott van, hogy a kapacitásom kevés hozzá, ill. annak az időpontja amikor ezt használatba is tudom venni az elkeserítően messze van.
És most itt van a dilemma. Csináljam úgy ahogy eddig, és akkor majd jó sokára lesz egy jó rendszer a munkámhoz. Vagy kezdjek el dokumentálni, meg önreklámozni (amihez nem értek, nincs érzékem, és még csak nem is szívesen csinálok) egy gyorsabb sikerrel kecsegtető, de igen bizonytalan cél érdekében. Az eddigiek nem nagyon bátorítottak fel erre.

Doxygen azert sallang, mert az ég világon semmit nem mond el a következőkről:
- Architektura, felepites
- Modulok, részegységek es kapcsolataik
- Funkcionális kovetelmenyek
- Hogyan is kellene működnie az egészben.

Ha ezeket az infokat at tudod adni valakinek, azzal nagyságrenddel könnyítés meg valakinek a bekapcsolodasat a projektbe, szemben egy Doxygennel generált valaminel, amit sok esetben kivált egy jobb IDE is.

De igazabol mar nem ertem, hogy mi a célod: mondod, hogy ezen-azon lehetne fejlődni, de te toled csak a panasz jon, hogy hat de olyat meg nem csináltál es hogy akkor azzal foglalkozni kellene...

----------------
Lvl86 Troll, "hobbifejlesztő" - Think Wishfully™

Az a baj kedves HUP társak, hogy a legritkább esetben keresitek az igazságot a másik hozzászólásában, ehelyett mindenáron a saját igazatok megtámogatásával foglalkoztok. Tudomásul kellene venni azt, hogy a való világ nem digitális, vagyis nem két kategória létezik: igaz vagy hamis. Sőt talán pont ez a kettő ami nem létezik.
Miközben abból amit mondani akartam nem ragadt meg semmi (illetve semmi jele), azonnal lecsaptál a Doxygen-es célzásomra. Amit felsoroltál az valóban hiányozni szokott egy Doxygen-es doksiból, de egyrészt nem muszáj belőle hiányoznia, másrészt ettől az még dokumentáció. Én a Qt-hez két segédletet használok. Legalább 90%-ban a hozzá adott Doxygen-el generált doksit. És ha valami nem áll össze, akkor előveszek egy könyvet, amik pont azokat tartalmazza a miket te hiányoltál fentebb. Az érveid helyesek, az az állításod pedig, hogy a doxygen egy sallang, szerintem csak egy roszz lehetőség, vagy rész igazság.
"Doxygennel generált valaminel, amit sok esetben kivált egy jobb IDE is."
Na ilyen IDE nekem is kéne, ami megmagyarázza mit csinál az osztály, és mit csinálnak a metódusok.
Megint teljesen igazad van, ha feltételezzük, hogy egyetlen szó érdemi kommentet sem írt a programozó. Láttam már ilyet. Na ott tényleg csak sallang volt.

És végül, ha a célom eddig nem derült ki, az gáz, de megpróbálom összefoglalni:
Van egy projekt, amit eddig szinte egyedül csináltam.
Ez a projekt szerintem egy rendkívül hasznos eszköz lenne rendszergazdáknak, akik hasonló rendszereket üzemeltetnek mint én.
A rendszerbe igyekeztem beleálmodni mindent, ami az előző két hasonló célú szintén általam fejlesztett rendszerből hiányzott (munkám során hiányoltam).
Sajnos ennek az lett a következménye, hogy a rendszer túl bonyolult lett, egy egyszemélyes projekthez mindenképpen.
Arra teszek bátortalan kísérletet, hogy támogatást szerezzek a befejezésére (nem pénz, legyen kivel megbeszélni, és legyen még valaki a ki kódol).
Bármily meglepő, ha valaki tud programozni, még nem biztos hogy képes egy használható dokumentáció megírására is, ezen az sem változtat ha az nélkülözhetetlen.
Két lehetőség közül választhatok:
Megerőltetem magam és megszülök egy valószínűleg nem túl jó dokumentációt. Ez tovább hátráltatja a projektet, de így nagyobb eséllyel várhatom a csodát, hogy valaki csatlakozik.
Másik lehetőség, folytatom úgy ahogy eddig, és ha megérem lesz belőle valami.
Nem mintha döntésre jutottam volna, de elkezdtem (újra kezdtem) írni egy dokumentációt, amit kiraktam egyenlőre félkészen a web-re, és írom tovább.

"Egyenlore a darabolos gyilkos fog majd vagni, amikor kiviszi a darabjaidat a kertbe, de egyelore meg varja, hogy elaludj"

Mindenkepp erdemes megirni a dokumentaciot, akkor is, ha magadnak csinalod. Ha barmiert van egy hosszabb kihagyas, utana sokkal jobban bele tudsz razodni, ha van valami, amit elolvashatsz. Es a jo dokumentacio olyan, mint a jo szoftver: sosincs teljesen kesz. Akar menet kozben is irhatsz hozza dolgokat, ha ugy latod, hogy hianyzik. Ami igazabol energiat igenyel, az egy struktura kialakitasa, ez viszont teljesen projektfuggo.
--

Ki oda vagyik, hol szall a galamb, elszalasztja a kincset itt alant. 

"Jelenleg sem arról van szó, hogy én ezt a projektet nem tudnám befejezni. A baj ott van, hogy a kapacitásom kevés hozzá, ill. annak az időpontja amikor ezt használatba is tudom venni az elkeserítően messze van."

Az a baj, hogy munkat megsporolni csak befektetett munkaval tudsz. Ha most raszanod az idot, hogy dokumentalj, az sokszorosara noveli az eselyet annak, hogy valaki bekapcsolodik.

Ha nem lesz tul suru a hetvegem, akkor megnezem a cuccost, es osszedobok valami Githubos wiki-kompatibilis cuccot a doksijabol.
--

Ki oda vagyik, hol szall a galamb, elszalasztja a kincset itt alant. 

Amióta a doksi kezdeményt, meg az API doksiját kitettem a web-re, a kis számú érdeklődőkel szemben (talán a többesszám jogos) a törni vágyók máris számbeli fölényben vannak.
Ezek szerint a hétvégén nem dolgoztam hiába, így legalább van aki jól szórakozik.
Ha valaki mégis a weblapra téved, mint érdeklődő, annak érdemes néha F5-öt nyomni.