Așa sa întâmplat că, în proiectele noastre, întreținerea documentației tehnice este în întregime pe umerii dezvoltatorilor, în conformitate cu principiul: modificări în codul proiectului - actualizarea documentației. Documentația în sine era un set de documente Word stocate împreună cu codul sursă pentru VCS. Această abordare a organizației de dezvoltare a existat de foarte mult timp, dar cu câțiva ani în urmă am decis să participăm la posibilitatea de a menține o documentație de proiect diferită de instrumentele MS Office.
Au existat mai multe motive pentru aceasta:
- Primele și, probabil, cele mai importante - conflicte frecvente în editarea în comun a fișierelor.
- Cel de-al doilea motiv - deși au existat o mulțime de documente, toate au avut o structură similară și, în multe privințe, s-au suprapus în conținut (datorită particularităților arhitecturii proiectului). Și, ca programatori adevărați, nu eram mulțumiți de "duplicarea" textului.
- Și, în final, lupta veșnică cu stiluri de design.
Toate aceste probleme sunt suprapuse pe ele și-au făcut din ea, și așa nu place foarte mult procesul de actualizare a documentației privind gradul de severitate insuportabilă a pedepsei. Sa întâmplat că, după mai multe ore de tine zmangaleala cu un sentiment de implinire este încercarea de a „umple“ modificările în SVN și de a obține știri că cineva este lipsit de bucurie mai rapid decât tine, sau pur si simplu, pur și simplu a uitat să actualizeze înainte de a începe. În orice caz, acest lucru a însemnat că o pauza de fum va trebui să fie amânat un pic. În plus față de textul era necesar să se acorde o atenție și stilul vizual, ceea ce este destul de o regularitate surprinzătoare pentru un motiv oarecare, pentru a „sparge“ (de exemplu, numerotarea lista a început de la început, într-un loc care va continua, și altele asemenea). Mai mult decât atât, nu toate astfel de „eșec“ sa dovedit ușor de a stabili, uneori, a început să pară că Cuvântul a trăit o parte din viața lui, și el nu-mi pasă de dorințele dumneavoastră la design.
Astfel, alternativa noastră la MS Word a fost aceea de a îndeplini următoarele criterii:
Ca urmare a unei căutări lungi, am realizat că nu există atât de multe soluții care să corespundă cerințelor noastre: DITA și DocBook. DITA părea imediat prea "puternic" și dificil pentru tranziție, dar pe DocBook am decis să ne oprim. În general vorbind, căutarea de soluții alternative a fost foarte treptat și înainte am dat seama că „astfel încât să nu pot merge pe“ și finaliza tranziția la DocBook - a luat mai mult de o zi, și a efectuat un număr mare de experimente asupra a ceea ce a fost la momentul în mâinile noastre. În primul rând a încercat să păstreze documentele în format WordML, care într-o anumită măsură, a rezolvat problema cu schimbările de fuziune - acum fuziunea nu se termină întotdeauna în conflict, dar rezoluția manuală a conflictelor în markup a fost foarte inconfortabil. De asemenea, a încercat să împartă documentele în fragmente, reducând astfel posibilitatea schimbărilor de conflicte și încercând să le reutilizeze. Ideea nu a avut succes. Și așa, treptat, prin încercare și eroare, toți au decis să treacă complet la DocBook, deoarece, în opinia noastră, a trebuit să elimine toate problemele noastre.
Ce este DocBook?
Dacă dintr-o dată, cine nu știe, DocBook este un standard pentru descrierea documentului și nimic util, cu excepția faptului că nu standardizează conținutul. Și standardul este destul de vechi, iar mulți, din anumite motive, sunt considerați învechite.
Scrierea unui document în format DocBook este foarte asemănătoare cu lucrul cu HTML, folosește numai propriul set de etichete și reguli pentru utilizarea lor.
Acest exemplu demonstrează o descriere a cărții constând dintr-un capitol cu titlul "Primul capitol" care conține un paragraf cu textul "Hello Word!". O listă completă a etichetelor, precum și exemple de utilizare a acestora, pot fi găsite pe site-ul proiectului www.docbook.org. De la mine vreau să observ că setul de etichete pentru descrierea conținutului este foarte (chiar foarte foarte) mare, dar în munca zilnică folosim aproximativ 20.
Conversia unui document DocBook
În scopul de a aduce documentul nostru DocBook în orice adecvat pentru formatul de citire sau de imprimare pe care doriți să utilizați un transformator (sau chiar o conducta de mai multe transformatoare unul de altul), care se bazează pe conținutul documentului, și, de obicei stiluri vizuale vor forma documentul final.
De obicei, DocBook-xsl este folosit pentru transformare (deși există mai multe moduri exotice). Din cutie, suportă deja mai multe formate de document - html, xsl-fo, manpages etc. În cazul în care aveți nevoie de un alt format de prezentare, puteți continua lanțul de transformare. Deci, pentru a primi un document în PDF, se utilizează de obicei următoarea schemă:
Și aici începe cel mai interesant. Stilurile implementate implicit în DocBook-xsl vă permit să obțineți aspectul obișnuit al documentului, dar, de obicei, acestea necesită încă personalizarea.
Dezvoltatorii de stiluri docbook-xsl au avut grijă de această oportunitate și au pus în aplicare în acest scop mecanisme speciale:
- Parametrii cei mai obișnuiți pentru crearea unui document pentru fiecare dintre formatele acceptate sunt făcuți într-un fișier separat param.xsl, iar pentru fiecare dintre acestea există o descriere mai mult sau mai puțin detaliată.
- Există șabloane speciale pentru formarea de șabloane personalizate.
- Prezența unor șabloane speciale, goale implicite pentru suprimarea ulterioară a acestora.
De cele mai multe ori, pentru a gestiona procesul de formare a documentelor, vă dezvoltați propriul stil XSL rădăcină, așa-numitul "Driver", în care deja ajustați toți ceilalți parametri de transformare. Deoarece, fiecare format final din DocBook-xsl este reprezentat de un set propriu de șabloane, atunci "driverul" pentru fiecare dintre ele trebuie să scrie unul separat. De exemplu, folosim două formate finale pentru reprezentarea documentelor (xsl-fo și htmlhelp) și, prin urmare, avem două "drivere" și două seturi de stiluri redefinite.
Alegerea procesoarelor xslt și fo
Pentru a lucra cu DocBook-XSL are nevoie de procesor XSLT XSLT acceptă versiunea 1.0. (Există realizarea docbook-xsl pentru versiunea 2.0, dar nu știu cât de mult este stabil). În momentul de față, există mai multe soluții de flux de lucru pentru o varietate de platforme - astfel încât să apară aceste probleme. În proiectele noastre folosim Saxon, deși o versiune mai veche - saxon 9.1.0.8J, deoarece în ultimul liber elimina complet suport pentru EXSLT (necesar pentru profilarea documentelor) extensii, și nu a existat nici o certitudine că extensia Saxon pentru sprijin sintaxa.Valorile care merge impreuna cu stiluri Acesta va lucra în noi.
Pentru a genera documente de la xsl-fo aveți nevoie de un fo-procesor. Aici lucrurile sunt mult mai rele - de la procesoarele de lucru am încercat personal două FOP (opensource) și XEP (RenderX XEP Engine - puțin plătite). Există mai multe procesoare pentru fo, dar personal nu am încercat să lucrez cu ele și nu pot spune nimic despre ele.
Principalul avantaj al FOP este că este gratuit, dar există și un minus - din "caseta" nu suportă limba rusă. La prima cunoaștere cu el, nu l-am putut face să lucreze cu alfabetul chirilic. În mod ironic pe internet o mulțime de articole despre ea, dar toate acestea au fost fie foarte vechi (care a propus pentru a reconstrui POP cu fonturile necesare) sau erori de conținut, care nu produc rezultatele dorite. În final, totul sa dovedit a fi foarte simplu, însă alegerea noastră a căzut deja pe XEP. XEP funcționează bine cu versiunea chirilică imediat după instalare și, în principiu, nu necesită o configurație suplimentară, dar costă 400 $ - și versiunea desktop. Diferența în calitatea redării nu poate fi judecată, dar puteți compara pentru dvs. (în exemplu există fișierele colectate de ambele fo-procesoare).
Personalizați stilul de design
Pentru setări de stil de calitate trebuie să cunoască limba un pic de transformare XSL, precum și limba documentului final de marcare. Din păcate, avem o echipa de la momentul trecerii la DocBook o astfel de competență nu a fost atât de setare ne-a luat suficient timp - în special pentru formatul FO. Deși rețeaua și există multe site-uri cu informații despre acest subiect (în special valoros în opinia mea „DocBook XSL: Ghidul complet“) completează imaginea este foarte dificilă dintr-o dată. Așa că am decis să acționeze în conformitate cu principiul - „mai bine să vezi o dată decât să auzi de o sută de ori“ și a pregătit un exemplu de stil pentru XSL-FO (aproximativ la fel ca și folosim în proiectele mele), împreună cu textul original al articolului și POP configurat.
Singurul punct pe care doresc să subliniez, și care la început poate fi confuz - Setarea fontului și limba documentului. În mod implicit, XSL-FO incluse fonturi care nu acceptă chirilică, iar dacă nu suprascrie aceste setări sau pentru a le permite o greșeală (trebuie să vă asigurați că FO-procesor este configurat pentru a lucra cu font specificat), ieșirea procesorului FO probabil obține imposibil de citit documentul. limba documentului afectează crearea de intrări AutoText pentru numele de elemente ale cărții (capitole, cartea, etc.). În principiu, stabilirea acestor parametri au numai că va furniza documentul „corect“. De asemenea, este probabil să aibă o dorință de a schimba aspectul paginii coperta documentului. Acest lucru se poate face cu ajutorul special instruiți în șablonul DocBook-XSL. Pentru a face acest lucru, trebuie să definiți propria versiune a fișierului „/fo/titlepage.templates.xml“ și cu procesorul de ajutor XSLT și șablonul „/fo/titlepage.templates.xsl“ get stil personalizat pentru conectarea la „conducătorului auto“. În unele cazuri, mecanismele de configurare încorporate nu sunt suficiente, iar apoi trebuie să avem în driver suprascrie stilurile originale docbook-xsl în mod clar.
concluzie
tranziția completă la DocBook, am luat o mulțime de timp. În primul rând, era necesar să se aducă documentația deja scrisă. Aici am încercat diverse utilități, cum ar fi antiword, dar din cauza numărului mare de artefacte, sa decis să o facă manual (artefacte sunt obținute ca urmare a erorilor de formatare în documentul original, și din cauza naturii de script-uri de traducere). De asemenea, o mulțime de timp luat de la noi pentru a dezvolta propriile lor stiluri, căutând mediul pentru dezvoltarea documentelor (în final stabilit pe Notepad ++) și mediul de configurare. Părea o sarcină ușoară, dar punerea sa în aplicare este bumping în mod constant în orice probleme. Din păcate, nu multe informații cu privire la DocBook, iar dacă vorbim despre segmentul rusesc - Practic nu are. Dar, în cele din urmă am fost mulțumiți.
Din moment ce echipa noastra a fost mutat în documentația tehnică în DocBook a trecut mai mult de un an, și nu ne putem imagina pentru mine orice altă opțiune. În total, ceea ce am vrut să realizăm prin trecerea la DocBook - am obținut:
- Ai uitat ce conflictele din documentele atunci când se lucrează în VCS, chiar și atunci când se utilizează GitFlow (cu aceeași rezervă ca și la începutul articolului, și-au făcut modificări - reflectate în documentația).
- Aproape complet eliminat duplicarea aceluiași text în documente diferite. Datorită profilării DocBook, sa dovedit a face documentul mai flexibil, iar scrierea de documente este mai puțin plictisitoare. Aici sensul principal al măsurii, deoarece descompunerea complexă a documentului sursă complică foarte mult navigarea pe aceasta și editarea ulterioară.
- A uitat practic modul de formatare a documentelor în Word, sau mai degrabă a uitat cum să-l formatezi. Acum, elaborarea documentației - scriind doar textul documentului.
- Domeniul mare de creativitate în ceea ce privește integrarea în procesul general de dezvoltare a software-ului.
În mod natural, în plus față de plusuri, există dezavantaje:
- Cea mai urgentă problemă în prezent este interacțiunea cu alte divizii ale companiei. Din motive evidente, dar echipa noastră sa mutat la DocBook, și toate celelalte utilizare MS Word, iar atunci când avem nevoie pentru a face un schimb de date - atunci trebuie să o facem manual. Din fericire, acest lucru se întâmplă foarte rar și este de obicei limitat la câteva paragrafe din text.
- Complexitatea punerii în aplicare a unor non-standard pentru DocBook abordări pentru formatarea documentelor, în special, de multe ori apare necesitatea de a implementa mai multe pagini în orientarea peisaj, dar încă nu au învățat cum să facă acest lucru (spre rușinea noastră) și avem la acest punct, pentru a primi într-un fel diferit. Dar eu sunt 100% sigur că acest lucru se poate face, și problema nerezolvată de acest lucru poate fi explicat nevoie nu atât de urgentă. De exemplu, când trebuie să inserăm formule într-un document - răsucirea MathML a durat mai puțin de o jumătate de zi.
Scopul acestui articol este de a aduce cititorilor care elaborează documentația tehnică în programele de birou că există instrumente mai potrivite. Pentru cei care au ceva timp sa uitat la o parte, sau DITA DocBook, da unele impuls și sfaturi pentru a merge - de fapt, cel mai dificil lucru pentru a începe! De asemenea, ar fi foarte interesant să vedem ce abordări sunt luate în alte echipe și experiența lor de implementare.
Articole similare
Trimiteți-le prietenilor: