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

• (14.06.2004 Dagblog) Spuštěn český server DocBook.cz
• (12.11.2003 Dagblog) DocBook — dokumentace v hrsti