středa 26. ledna 2005

Do pranice: Dokumentační systém

Čas od času se na mě někdo obrátí s prosbou o drobnou konzultaci. Nejinak tomu bylo v případě hledání ideálního dokumentačního systému, se kterým se na mě obrátil Róbert Gál.

Prave mame problem, ze musime akunte najst dokumentovaci system, ktory by splnal tieto poziadavky:

  • tymova pouziti - vice lidi editovat soucacne
  • snadna editace - rychlost, dostupnost
  • snadne vyhledavani-fulltext, wildcards
  • exporty do html, pdf
  • podpora cvs - moznost uprav mimo pracoviste (offline)
  • krizove odkazy
  • rozsiritelnost, podpora

jednie co sme nasli je docbook, ale to je vsak prosty zaklad, plus k tomu nejaky opens. editor a cvs. Neni to nic moc... Nevedel by si nieco doporucit? Co vy tam pouzivate? Este som nasiel twiki, co splna vsetky vyssie uvedene poziadavky, ale uklada (ako kazde wiki) data do databaze(xml by bol lepsi).

Uvazovali sme o wiki systemoch (napr. twiki), ktore splnali nase poziadavky, avsak nenasiel som system na baze xml. Kazde wiki si uklada data do dbs, vacsinou pouzivaju nejaky vlastny format. Tak sme sa spolocne zhodli na docbooku, podobne ako Vy. Budeme sa synchronizovat cez cvs. Akurat su tu este 2 dalsie problemy, ktore musime vyriesit:

Snadne vyhledavani-fulltext, wildcard

toto asi budeme riesit tak, ze server vygeneruje html subory z docbooku v nejakom pravidelnom intervale (30min?). To sa da velmi pohodlne napr. s Mavenom (plugin sdocbook...). Potom, zda sa, ze pouzijeme Eclipse-help system k vytvoreniu pekneho helpu z tych html suborov, ktory by potom vypadal ako na adrese http://help.eclipse.org/help30/index.jsp (viz dalsiu adresu: http://www-106.ibm.com/developerworks/opensource/library/os-echelp/)

Vygenerovanu dokumentaciu v ecli.help.systeme by sa dalo dokonca lahko integrovat do eclipsy. Vyvojar by sa mohol pozriet na firemnu dokumentaciu priamo v eclipse. Ale, pravdepodobnejsie je, ze spristupnime dokumnenty na nejakej lokalnej url adrese.

Snadna editace - rychlost, dostupnost

Na druhy problem existuje viac rieseni: k editaciu docbooku pouzijeme nejaky open-source wysiwyg editor. (na meno si uz nespomninam), alebo openofficy. Skoda, ze NEEXISUTJE gui plugin docbooku do eclipsy. To ma prekvapilo. Keby si mal nejake napady, na rychlu editaciu doc-bookov, aby mal co nejnizsie 'learning-curve' pre cely tym

Myslím si, že s CVS a Docbookem není co řešit. Menší nevýhodou Docbooku je větší 'learning-curve' pro většinu jeho uživatelů, tedy pokud se nejedná o HTML/XML kodery. Na druhou stranu pro psáni 80% dokumentace stačí několik málo elementu (odstavec, seznam, nadpis+kapitola, obrázek, odkaz, citace ...), které je schopný absorbovat každý. Spíše jde o obecný konsensus celého týmu v přijmutí Docbooku jako nástroje pro psaní dokumentace.

U nás ve firmě je Docbook standardem pro dokumentaci k IS. Všichni metodici museli přejit z Wordu na Docbook. Samozřejmě jim byla poskytnuta podpora ve formě školení a v v upraveném editoru pro psaní dokumentace. Editor má nastavenou, formou spouštění batch dávek, validaci, kontrolu pravopisu a generovaní výstupní dokumentace. Zmíněný editor je EditPlus, tedy žádný wysiwyg editor. Dále jsou k dispozici interní materiály pro psaní v Docbooku, v podstatě help.

Ještě bych se vrátil k tomu editoru, podle mě je problém sehnat kvalitní a cenově dostupný wysiwyg editor Docbooku. Alespoň to bylo v době kdy jsme na Docbook přecházeli. Pokud jsem teď koukal na podporu v OpenOffice, tak mi jeho podpora wysiwyg přijde absolutně v kontrastu s mou představou o wysiwyg. V případě OpemOffice mi přijde, že daný pisatel dokumentace bude muset tak či onak znát strukturu Docbooku, aby dokument vůbec vytvořil.

Vlastní generovaní dokumentace pomocí Mavenu se mi zamlouvá, jakákoliv automatizace je přínos. Moje idea je vyčlenit jeden produkční server s dokumentací a na něm mít cely proces zautomatizovaný (stažení, generování, packaging, publikování). K vyhledávaní se přímo nabízí Google Desktop Search. Na produkčním serveru dokumentace bych nainstaloval GDS, který by poskytoval vyhledávání komukoliv . Nevýhodou GDS je to, že běží pouze na Windows, pro jiné platformy bych volil například Lucene k čemuž mě inspiroval Dion Almaer článkem I love Lucene.

Související články