Просто така се случи, че в нашите проекти, техническа документация е разположена изцяло върху плещите на разработчиците, според принципа: Промените, направени в кода на проекта - обновен документацията. Тя беше набор от документи на Word документи, които се съхраняват заедно с изходния код под СВК. Този подход за развитие съществува от дълго време, но преди няколко години решихме да присъстват на възможността на проектна документация, различна от MS Office инструменти.
Имаше няколко причини за това:
- Първата и може би най-важно - чести конфликти с ко-редактиране на файлове.
- Втората причина - въпреки че документите са били толкова много, всички те имат сходна структура и до голяма степен се припокриват по съдържание (поради естеството на архитектурата на проекта). И колко е вярно програмисти не ни допадна "дублиране" на текста.
- И накрая, вечната борба със стилове.
Всички тези проблеми са наложени едно над друго и са изработени от него, и така наистина не прилича на процеса на актуализиране на документацията за непоносимата тежест на наказанието. Това се случи, че след няколко часа можете да драска с чувство на удовлетворение се опитва да "попълни" промените си в SVN и да получите безрадостни новина, че някой е по-бързо, отколкото си, или просто просто забравих да се актуализира, преди да започнете. Във всеки случай, това означава, че от почивка дим ще трябва да се отложи малко. В допълнение към текста, че е необходимо да се обърне внимание и визуален стил, което е доста изненадващо, редовност по някаква причина, за да "пробие" (например списък номерацията започва от самото начало, на място, което ще продължи и други подобни). Освен това, не всички такива "провал" се оказа лесно да се определи, понякога започва да изглежда, че Словото е живял някои от живота му, а той не ми пука за вашите желания за дизайн.
По този начин, нашата алтернатива на MS Word, трябва да отговаря на следните критерии:
В резултат на задълбочено търсене осъзнахме, че решенията да отговарят на изискванията ни, там не е толкова много: DITA и DocBook. DITA веднага ни се стори прекалено "силен" и се движи трудно, но на DocBook, ние решихме да спрем. Най-общо казано, търсенето на алтернативни решения е много постепенно и преди ние осъзнахме, че "така че да не може да отиде на" и да завърши прехода към DocBook - отне повече от един ден, и се осъществява с голям брой експерименти върху това, което е в момента в нашите ръце. На първо място се опита да запази документите в WordML формат, който до известна степен е решила проблема с промените за сливане - сега сливането не винаги се сложи край на конфликта, но ръководството разрешаването на конфликти в маркирането беше много неудобно. Също така се опита да се раздели документи на фрагменти, като по този начин се намалява възможността за промени на конфликти и да се опита да приложи на повторното им използване. Начинанието не беше много успешен. И така постепенно, чрез опити и грешки, все пак са решили да преминат изцяло към DocBook, защото по наше мнение, че трябва да се премахнат всички наши проблеми.
Какво е «DocBook»?
Ядох изведнъж, които не знаят, DocBook - е стандартно описание на документа, и нищо полезно, освен в случаите, стандартизация на съдържание не го прави. Още повече, че стандартът е доста стар, и много, по някаква причина, вече се счита за остаряла.
Писане на документ в DocBook формат е много подобен на работа с HTML, просто използва набор от етикети и правила за тяхната употреба.
Този пример показва, описание на книгата се състои от една глава със заглавие «първа глава», съдържаща алинея с текст «Hello Слово!». Пълен списък на етикетите, както и примери за тяхното прилагане може да шпионират www.docbook.org сайт на проекта. От себе си бих искал да отбележа, че набор от ключови думи, за да опише съдържанието на много (дори и много много) големи, но в ежедневната работа ние използваме около 20.
Документът се преобразува DocBook
С цел постигане на нашия документ DocBook във всеки подходящ за формат четене или за печат, който искате да използвате трансформатор (или дори на тръбопровод от няколко трансформатори един до друг), който се основава на съдържанието на документа и обикновено визуални стилове ще формира окончателния документ.
Обикновено се използва за трансформиране DocBook -xsl (макар че има и по-екзотични начини). Извън кутията вече поддържа множество формати на документи -. HTML, XSL-FO, Man-и т.н. Ако е необходимо формат представяне, то е възможно да се продължи веригата от преобразувания. Така че да се получи документа в PDF обикновено е използвана следната схема:
И това е мястото, където забавлението започва. Стилове изпълняват в по подразбиране е възможно DocBook-XSL да получат нормални по външен вид на документ, но обикновено все още се нуждаят тяхното персонализиране.
Разработчици стилове Docbook-XSL се внимава с тази възможност и са приложили за тази специални настройки:
- Най-често срещаните варианти за формирането на документа за всеки от поддържаните формати в отделен файл param.xsl и за всеки от тях имат повече или по-малко подробно описание.
- Има специални шаблони за формиране на потребителски шаблони.
- Наличието на специални, изпразнете стандартния шаблон за последващо регулиране.
Най-често, за да управлявате процеса на формиране на документа, разработен свой собствен стил корен XSL, така наречената "водача", което вече е в ход, за да прецизира всички останали параметри на трансформацията. Тъй като всяка целева формат в DocBook-XSL представи свой собствен набор от шаблони и "шофьор" за всеки от тях трябва да напишете отделно. Например, ние използваме две крайния формат за документа (XSL-FO и htmlhelp) и съответно да има две "шофьори" и двата набора от стил изключения.
Избор на XSLT процесор, и FO
За да работите с DocBook-XSL нуждае XSLT XSLT процесор поддържа версия 1.0. (Там е реализация DocBook-XSL за версия 2.0, но не знам колко е стабилна). В момента има много решения за управление за различни платформи - така че в случай на възникване на тези проблеми. В нашите проекти ние използваме Saxon, макар и по-стара версия - Saxon 9.1.0.8J, тъй като в последния свободен премахнете напълно подкрепа за EXSLT (необходими за профилиране документ) разширения, и не е имало сигурност, че саксонските разширение за оцветяване на синтаксиса подкрепа, която върви заедно с стилове Тя ще работи в новото.
За формирането на документите трябва да XSL-FO-FO процесор. Тук нещата са малко по-зле - на работните процесори Аз лично се опита два FOP (софтуера с отворен код) и XEP (RenderX XEP Двигател - малко доплащане). Все още има няколко работни FO процесори, но лично аз не съм го пробвал с тях да се работи и за какво да се каже за тях не мога.
Основният плюс на FOP е, че тя е безплатна, но има и минус - от "кутията" не поддържа руски език. На първата ни среща с него, ние не успя да я накара да работи с кирилицата. По ирония на съдбата в интернет много статии за това, но всички от тях са били или много стар (който предложи да се възстанови конте с необходимите шрифтове) или съдържат грешки, които не произвеждат желаните резултати. В крайна сметка, всичко е много просто, но нашият избор е паднал върху XEP. XEP работи чудесно и с кирилицата веднага след инсталацията и по принцип не изисква допълнителна конфигурация, но си струва $ 400 - с десктоп версията. Разликата в качеството на действие не може да се съди, но можете да сравните за себе си (в примера файлове се събират двата процесора FO-) за интереса.
Персонализиране на външния вид на стила
За качествени настройки на стила, което трябва да знаят езика малко XSL трансформация, както и на крайния език документ за маркиране. За съжаление, ние разполагаме с екип по време на преход към DocBook такава компетентност е не толкова настройката ни заведе достатъчно време - особено за FO формат. Въпреки, че мрежата и има много сайтове с информация по този въпрос (особено ценна, по мое мнение "DocBook XSL: Пълно ръководство") допълват картината е много трудно наведнъж. Затова реших да действа в съответствие с принципа - "по-добре да се види веднъж, отколкото чуете сто пъти" и подготвени пример за стил за XSL-FO (приблизително колкото ние използваме в моите проекти), заедно с оригиналния текст на статията и конфигуриран конте.
Единствената точка, на която искам да подчертая, и който на първо може да е объркващо - Настройка на шрифта и езика на документа. По подразбиране, XSL-FO включени шрифтове, които не поддържат кирилица, и ако не игнорирате тези настройки, или да им позволи грешка (трябва да се уверите, че FO-процесор е конфигуриран да работи с определен шрифт), на изхода на процесора FO-вероятно да получите нечетлив документ. език документ отразява създаването на записи автотекста за имена на елементи на книгата (глави, книгата и т.н.). По принцип, определянето на тези параметри са само ще осигури "правилната" документ. Също така е вероятно да имат желание да промените външния вид на заглавната страница на документа. Това може да стане с помощта на специално обучени в DocBook-XSL шаблон. За да направите това, трябва да зададете своя собствена версия на "/fo/titlepage.templates.xml" на файла и с помощта на XSLT процесор и шаблон "/fo/titlepage.templates.xsl" получите и персонализирани стил за връзката с "водача". В някои случаи, вградени механизми за конфигурация не са достатъчни, а след това трябва да имаме ясно в драйвера замени оригиналните стилове Docbook-XSL.
заключение
Пълен преход към DocBook, взехме много време. На първо място, е необходимо да се въвеждат вече писмена документация. Тук ние се опитахме различни комунални услуги като antiword, но поради големия брой артефакти, беше решено да го направите ръчно (артефакти са получени като резултат на грешки при форматирането на оригиналния документ, и поради естеството на превод скриптове). Също така много време отне от нас, за да разработят свои собствени стилове, търсене на околната среда за развитието на документи (в крайна сметка спря на Notepad ++) и конфигурация околната среда. Струваше ми се е лесна задача, но изпълнението му е постоянно блъскане в никакви проблеми. За съжаление, не може повече информация по DocBook, и ако говорим за руския сегмент - това практически няма. Но в края на краищата ние бяхме доволни.
Тъй като нашият екип е преместен на техническа документация в DocBook е преминал повече от една година, и не можем да си представим за себе си всеки друг вариант. Само това, което ние искахме да осъществи прехода към DocBook - сме постигнали:
- Забравена какво конфликтите в документите, когато работят в СВК, дори и при използване на GitFlow (със същото условие като в началото на статията, както и са направени промени - отразено в документацията).
- Почти напълно се отървах от дублирането на един и същ текст в различни документи. Поради профилиране DocBook оказа получаване на документа по-гъвкави и по-малко скучен документация писане работа. Основното нещо чувство за мярка, защото в комплекс-Хур разлагане на оригиналния документ значително усложнява навигацията върху него и да го редактирате.
- Почти забравена как да форматирате документ в Word, или по-скоро просто забрави как да форматирате. Сега, за развитието на документация - просто написването на текста на документа.
- Много място за творчество по отношение на интегриране в цялостния процес на разработка на софтуер.
Разбира се, в допълнение към предимствата има и недостатъци:
- Най-неотложния въпрос в момента - е взаимодействието с други ведомства. По очевидни причини, но нашият екип се премества в DocBook, и всяко друго използване на MS Word, и когато трябва да се направи обмен на данни - тогава ние трябва да го направите ръчно. Ползата от това е много рядко и обикновено се ограничава до няколко точки на текст.
- Сложността на изпълнението на някои нестандартни за DocBook подходи за форматиране на документи, по-специално, често възниква необходимостта от разполагане на няколко страници в хоризонтална ориентация, но все още не са се научили как да се направи това (в нашия срам) и имаме до този момент, се някак по-различно. Но аз съм 100% сигурен, че това може да се направи, а от нерешен проблем на това може да се обясни не толкова спешна нужда. Например, когато се наложи да вмъкнете формула в документ - на prikrutka MathML отне по-малко от обяд.
А целта на тази статия е да донесе на читателите, които се развиват на техническа документация в програмите на Office, че има по-подходящи инструменти. За тези, които имат известно време изглеждаше отстрани, или DITA DocBook, даде някакъв тласък и съвети, за да отидат - всъщност най-трудното нещо, за да започнете! Както е добре, че ще бъде много интересно да чуя какво подходите, които се в други отбори и техния опит в прилагането му.
Свързани статии