dokumentáció fejlesztés docbook

Ez csak azért történt, hogy a projektek műszaki dokumentáció terheli a vállán a fejlesztők szerint az elv: változtatásai a projekt kódja - frissítve a dokumentációt. Ő volt egy sor dokumentumot Word dokumentumok, amelyek együtt tárolják a forráskód alatt VCS. Ez a megközelítés a fejlődés létezett sokáig, de egy pár évvel ezelőtt úgy döntöttünk, hogy részt vegyen a lehetőségét a projekt dokumentáció eltérő MS Office eszközöket.

Ennek több oka volt erre:

Az első és talán a legfontosabb - a gyakori konfliktusok együttes szerkesztését a fájlokat.
A második ok - bár a dokumentumok annyi, mindannyian hasonló szerkezetű és nagymértékben átfedik egymást tartalommal (jellege miatt a projekt architektúra). És milyen igaz programozók nem illik hozzánk „párhuzamos” a szöveget.
És végül, az örök harc a stílust.

Mindezek a problémák egymásra, és a belőle készült, és így nem igazán szeretem a folyamat frissítése a dokumentáció az elviselhetetlen súlyosságát a büntetés. Úgy történt, hogy néhány óra elteltével irkafirka Önnek egyfajta teljesítmény próbál „kitölteni” a változásokat az SVN és kap örömtelen hír, hogy valaki gyorsabb, mint te, vagy csak egyszerűen elfelejtette frissíteni, mielőtt elkezdené. Mindenesetre, ez azt jelentette, hogy egy füst szünetet kell majd halasztani egy kicsit. Amellett, hogy a szöveget kellett figyelni és a vizuális stílus, ami elég meglepő szabályszerűségét valamilyen okból a „szünet” (például a lista számozását kezdődött a kezdetektől fogva, egy olyan helyen, amely folytatódni fog, és hasonlók). Ráadásul nem minden ilyen „hiba” Kiderült könnyű kijavítani, néha kezdett úgy tűnik, hogy az Ige élt néhány saját életét, és nem érdekel a kívánságát, hogy a design.

Így, a másik az MS Word meg kell felelniük az alábbi kritériumoknak:

Ennek eredményeként a kiterjedt keresési rájöttünk, hogy a megoldásokat, hogy megfeleljen a követelményeknek, akkor nem annyira: DITA és a DocBook. DITA azonnal látszott, hogy nekünk is „erős”, és nehezen mozog, de DocBook-, úgy döntöttünk, hogy hagyja abba. Általánosságban elmondható, hogy a keresési az alternatív megoldások már nagyon fokozatos, és mielőtt rájöttünk, hogy a „így nem mehet tovább”, és töltse ki az átmenetet a DocBook - volt több, mint egy nap, és végzett számos kísérlet alatt, amit annak idején a kezünkben. Először megpróbálta tartani a dokumentumokat WordML formátumban, hogy bizonyos mértékig oldotta meg a problémát az egyesülés változások - most az összefonódás nem mindig a végén a konfliktus, de a kézikönyv konfliktusok megoldásában a jelölésben nagyon kényelmetlen volt. Is megpróbálta osztani dokumentumok darabokra, ezáltal csökkentve a lehetőségét, konfliktus változások és próbálja meg végrehajtani az újrafelhasználás. A vállalkozás nem volt túl sikeres. És így fokozatosan, próbálgatással, még mindig úgy döntött, hogy teljesen váltani a DocBook- mert véleményünk szerint, volt, hogy távolítsa el az összes problémánkat.

Mi «DocBook-»?

Evett hirtelen, akik nem tudják, DocBook- - egy szabványos leírása a dokumentumot, és semmi hasznos, kivéve a szabványosítás a tartalom nem. Ezenkívül a szokásos elég régi, és sok, valamilyen oknál fogva, már elavultnak tekinthető.

Az írás a dokumentum DocBook nagyon hasonlít a dolgozó HTML, csak használ egy sor címkék és szabályok azok használatát.

Ez a példa azt mutatja leírását a könyv áll egy fejezetet a címe «Első fejezet» tartalmazó bekezdés a szöveget «Helló Szó!». A teljes lista a címkéket, valamint példák azok alkalmazását is kémkedni www.docbook.org helyszínre. Magamtól meg kívánom jegyezni, hogy a címke készlet tartalmának leírására egy nagyon (még nagyon-nagyon) nagy, de a napi munka használjuk 20.

DocBook forrás dokumentum

Annak érdekében, hogy a DocBook dokumentum bármely alkalmas olvasásra vagy nyomtatott formában a használni kívánt transzformátort (vagy akár egy csővezeték több transzformátorok egymással), amely alapján a dokumentum tartalmát, és általában a vizuális stílusok képezi a végső dokumentum.

Általában használt átalakítani DocBook -xsl (bár több egzotikus módon). Out of the box már támogatja a több formátumokhoz -. Html, XSLFO, man oldalak, stb Ha szükséges prezentációt méret, akkor lehet, hogy továbbra is a lánc transzformációk. Így kapjuk a dokumentum PDF általában használt a következő séma szerint:

És ez az, ahol a szórakozás kezdődik. Stílusok végre az alapértelmezett DocBook-xsl lehetséges normális megjelenésű dokumentumot, de általában még mindig szüksége van a testre.

A fejlesztők stílusok docbook-xsl gondoskodott erről a lehetőségről, és végrehajtották az e különleges rendelkezések:

A leggyakoribb lehetőség megalakult a dokumentum minden egyes támogatott formátumok külön param.xsl fájlt, és mindegyikük többé-kevésbé részletes leírást.
Vannak speciális sablonok kialakulásának egyéni sablonok.
A rendelkezésre álló speciális, ürítse az alapértelmezett sablon későbbi felülírás.

Leggyakrabban kezelni a folyamat kialakulásának a dokumentum kifejlesztette saját gyökér XSL stílus, az úgynevezett „vezető”, amely már folyamatban finomíthatja az összes többi paramétert az átalakulás. Mivel minden célformátumot DocBook-xsl bemutatta a saját sablonokat és a „vezető” mindegyikre külön kell írni. Például, mi használjuk a két utolsó formátum a dokumentum (XSLFO és HTMLHelp) és rendre van két „vezetők”, és a két stílus felülbírálja.

Válogatás XSLT processzor és a fo

Együttműködik docbook- xsl szüksége xslt xslt processzor támogatja 1.0 verzió. (Ott van a megvalósítás docbook- XSL 2.0 verzió, de nem tudom, hogy mennyi van stabil). Abban a pillanatban, sok munkafolyamat megoldások a különböző platformok -, hogy ezek a problémák merülnek fel. A mi projektek használjuk szász, bár egy régebbi verzióját - Szász 9.1.0.8J, hiszen az utolsó szabad teljesen eltávolítani támogatása EXSLT (szükséges profilalkotás dokumentum) kiterjesztéseket, és nem volt biztos, hogy a szász kiterjesztését szintaxiskiemelést támogatást, hogy megy együtt stílusok működni fog az új.

A formáció a dokumentumokat kell XSLFO fo-processzor. Itt, a dolgok egy kicsit rosszabb - a dolgozó processzorok én személyesen próbálta két FOP (opensource) és XEP (RenderX XEP Engine - egy kis felár ellenében). Van még néhány munkanapon fo processzorok, de személy szerint én még nem próbáltam velük dolgozni, és semmit sem mondani róluk nem tudok.

A fő plusz a HOP, hogy ingyenes, de van egy mínusz - a „box” nem támogatja az orosz nyelvet. A mi első találkozó vele, nem sikerült, hogy működjön együtt a cirill ábécét. Ironikus az interneten egy csomó cikket róla, de mindegyikük vagy nagyon régi (amely azt javasolta, hogy újjáépítsék a HOP, a szükséges betűtípusok), vagy hiba, amely nem termel a kívánt eredményt. A végén, minden nagyon egyszerű, de a választás esett a XEP. XEP kiválóan működik a cirill ábécé közvetlenül a telepítés után, és elvileg nem igényel további konfigurációt, de megéri a $ 400 - az asztali változat. A minőségi különbség rendering nem tudja megítélni, de akkor össze magad (a példában fájlok összegyűjtjük mind fo-feldolgozók) kamat.

Testre megjelenését a stílus

A minőségi stílus beállításokat meg kell tudni, hogy a nyelv egy kicsit XSL transzformáció, valamint a végleges dokumentum jelölőnyelv. Sajnos, van egy csapat idején átmenet DocBook ilyen hatásköre nem volt olyan beállítás elvittek elegendő idő - különösen a FO formátumban. Bár a hálózat és sokan vannak helyek az információt ebben a témában (különösen értékes a véleményem „DocBook XSL: The Complete Guide”) teszi teljessé a képet nagyon nehéz egyszerre. Így elhatároztam, hogy cselekedni elve szerint - „jobb, hogy egyszer, mint hallani százszor”, és készítettek egy példa a stílus XSLFO (körülbelül ugyanaz, mint amit használhatok a projektek) együtt az eredeti szöveg a cikk és konfigurált FOP.

Az egyetlen pont, amelyre szeretném kiemelni, és amely az első zavaró lehet beállítása - font és a dokumentum nyelve. Alapértelmezésben a XSLFO benne betűtípusok, amelyek nem támogatják a cirill és ha nem felülírják ezeket a beállításokat, vagy lehetővé teszik számukra a hiba (meg kell győződnie arról, hogy a fo-processzor úgy van konfigurálva, hogy működik a megadott font), a kimenet a processzor fo valószínűséggel kap olvashatatlan dokumentumot. nyelvet érinti létrehozását AutoText bejegyzéseket nevét eleme a könyv (fejezetek, könyv, stb.) Elvileg a beállítást ezen paraméterek csak ad „korrekt” a dokumentum. Valószínű az is, hogy van egy vágy, hogy módosítsa a megjelenését a címlapon a dokumentumot. Ezt meg lehet tenni a segítségével speciálisan képzett docbook- xsl sablont. Ehhez meg kell adni a saját verzióját a fájl „/fo/titlepage.templates.xml”, és segítségével XSLT processzor és sablon „/fo/titlepage.templates.xsl” A személyre szabott stílus a kapcsolatot a „vezető”. Bizonyos esetekben, a beágyazott konfiguráció mechanizmusok nem elég, és akkor kell egyértelműen a járművezető felülírja az eredeti stílusok docbook-xsl.

következtetés

Teljes átmenet DocBook- vettünk egy csomó időt. Először is szükség volt, hogy a már írásos dokumentáció. Itt megpróbáltuk különböző segédprogramok, mint antiword, hanem azért, mert a nagyszámú leletek, úgy döntöttek, hogy tegye meg kézzel (leletek kapunk miatt formai hiba az eredeti dokumentumban, valamint amiatt, hogy a természet a fordítás scriptek). Szintén sok időt vett el tőlünk, hogy dolgozzák ki a saját stílus, keresi a környezet fejlesztésére vonatkozó dokumentumokat (a végén telepedett noteszbe ++) és konfigurációs környezetet. Úgy tűnt, egy könnyű feladat, de a megvalósítása folyamatosan nekimegy a problémákat. Sajnos, nem sok információt a DocBook- és ha beszélünk az orosz szegmens - gyakorlatilag nincs. De a végén mi voltunk elégedettek.

Mivel a csapat költözött műszaki dokumentáció DocBook átment több mint egy éve, és nem tudjuk elképzelni magam más választása. Csak mi akartuk elérni az átmenet DocBook - elértük:

Elfelejtette, mi a konfliktusok a dokumentumokat, ha dolgozik a VCS esetén is GitFlow (azonos feltétellel mint a cikk elején, és olyan változtatásokat - tükröződik a dokumentációt).
Szinte teljesen megszabadult a felesleges ugyanaz a szöveg különböző dokumentumokat. Due profilalkotás DocBook kiderült, hogy a dokumentum rugalmasabbá és kevésbé unalmas írás dokumentációs munka. A legfontosabb dolog, arányérzék, mert egy komplex chur bomlása az eredeti dokumentum nagyban megnehezíti a navigációt, és szerkesztését.
Majdnem elfelejtette, hogyan kell formázni a dokumentumot a Word, vagy inkább csak elfelejti, hogyan kell formázni. Most, a fejlesztési dokumentációt - csak írásban a szöveg a dokumentumban.
Sok szoba a kreativitás szempontjából integrálása az általános szoftverfejlesztési folyamat.

Természetesen amellett, hogy az előnyök vannak hátrányai is:

A legégetőbb probléma abban a pillanatban - az együttműködés más szervezeti egységek. Nyilvánvaló okokból, de csapatunk költözött DocBook- és minden egyéb felhasználás MS Word, és amikor kell, hogy egy adatcsere - akkor meg kell csinálni kézzel. Az előnye ennek a nagyon ritka, és általában csak egy-két bekezdésnyi szöveget.
A komplexitás végrehajtásának néhány nem szabványos DocBook megközelítések formázását dokumentumokat, különösen, gyakran felmerül az igény, hogy telepíteni több oldalt fekvő helyzetben, de még mindig nem tanulta, hogyan kell csinálni, hogy (a mi szégyen), és van, hogy ezen a ponton, hogy valahogy más. De én vagyok 100% -ig biztos, hogy ez nem lehet tenni, és a megoldatlan probléma ez azzal magyarázható, nem olyan sürgős. Például, amikor meg kellett szúrni egy képletet a dokumentumban - a prikrutka MathML volt kevesebb, mint délben.

És a célja ennek a cikknek az, hogy az olvasók, akik a fejlődő technikai dokumentáció Office programok, hogy több megfelelő eszközökkel. Azok számára, akik egy kis időt nézett oldalra, vagy a DITA DocBook- ad némi lendületet, és tippeket, hogy menjen - valójában a legnehezebb dolog kezdeni! Valamint, hogy nagyon érdekes lenne hallani, amit módszereit más csapatok élmény és a végrehajtás.

Kapcsolódó cikkek

előző ◈ a következő