Понякога не само самата документация, но и процесът на работа с нея може да бъде критичен. Например, в случай на проекти, голяма част от работата е свързана именно с подготовката на документацията, а неправилният процес може да доведе до грешки и дори до загуба на информация, следователно и до загуба на време и печалба. Но дори и ако тази тема не е централна в работата ви и е на периферията, правилният процес все пак може да подобри качеството на документа и да спести време.
Предложеният тук подход, с , има ниска бариера за влизане. Технически, още утре можете да започнете да работите по нов начин.
Формулиране на задачата
Трябва да създадете определен документ или комплект от документи. Може би това е проектна документация или протоколиране на вашата мрежа, или нещо по-просто, например, трябва да опишете процесите в компанията или в отдела си. Общо взето, става дума за всеки документ или комплект от документи с текст, изображения, таблици… Ще усложним задачата с това, че
- тази работа предполага съвместен труд, усилия на група или няколко групи служители
- на изхода желаете да имате документ в определен формат, с атрибути на корпоративен стил, създаден по определен шаблон. За конкретност ще приемем, че това е MS Word (.docx)
10 години назад подходът щеше да бъде еднозначен: щяхме да създадем MS Word документ или документи и по някакъв начин да организираме работата по промените.
И такъв подход все още е в сила. Включително и големи интегратори го използват при създаването на проектна документация. Но интуитивно е ясно, че ако наистина интензивно, с много корекции и обсъждания, работите над документ за продължителен период, този подход не е особено удобен.
Пример
Силно усетих този проблем, работейки в един голям интегратор. Процесът на изменение на проектната документация беше следният:
- инженерът сваля последната версия на MS Word (.docx) документа
- променя заглавието
- внася корекции в режим на проследяване
- изпраща документа с корекциите на архитекта
- изпраща също списък на всички поправки с коментари
- архитектът анализира промените
- ако всичко е наред, копира данните от промените в файла с последната версия, променя версията, публикува на общ ресурс
- ако има забележки, се инициира обсъждане (имейл или срещи)
- достига се консенсус
- нататък точки 3 — 9
Докато работата не беше интензивна, това все пак работеше по някакъв начин. Но в определен момент този процес стана узкото място на целия проект и доведе до проблеми. Става въпрос, че всичко става лошо, когато промените се извършват често и едновременно от няколко екипа.
Когато преминахме на етапа на предварително тестване, започнаха да се проявяват различни проблеми и, макар и по малко, документацията трябваше да се променя често — четири различни екипа, ежедневно, практически едновременно, с обсъждания. Всички тези промени преминаваха през един инженер — архитекта. Файлът с дизайна на проекта беше огромен и в резултат на това архитектът беше натоварен с рутинна работа, свързана с голямо количество копиране и редактиране, правеше много грешки, наложи се всичко да се проверява отново, да се пренасочва и като цяло беше близо до хаос.
В този случай този подход, подходът на работа с документа MS Word, работеше с голямо усилие и създаваше проблеми.
Git, Markdown
Изправяйки се пред проблема, описан в примера по-горе, започнах да изследвам този въпрос.
Видях, че все по-широко се използва в сътрудничество с при създаването на документи.
Git е инструмент за разработка. Но защо да не го използваме за процеса на документиране? В този случай проблемът с многопотребителската работа е разрешен. Но за да можем в пълна степен да използваме възможностите на Git, ни е нужен текстов формат на документа, трябва да намерим друг инструмент, не MS Word, и за тези цели Markdown е отличен вариант.
Markdown е прост език за текстова маркировка. Той е предназначен за създаване на добре оформени текстове в обикновени TXT файлове. Ако създадем документите си в Markdown, връзката Markdown — Git изглежда естествена.
И всичко ще е наред, и на това място можеше да се постави точка, ако не беше нашето второ условие: «на изхода ни е необходим документ в определен формат, с атрибути на корпоративен стил, създаден по определен шаблон» (и ние се договорихме в началото, че за ясност това ще бъде MS Word). Тоест, ако решим да използваме Markdown, трябва да преобразуваме този файл в .docx формат от необходимия вид.
Съществуват програми за конвертиране между различни формати, например, .
Можете да конвертирате Markdown файл в .docx формат с тази програма.
Но все пак, трябва да се разбере, че, първо, не всичко, което се съдържа в Markdown, ще бъде конвертирано в MS Word и, второ, MS Word е цяла страна в сравнение с компактен, но все пак малък град, наречен Markdown. Има огромно количество съдържание в Word, което не присъства в Markdown. Не може просто така да вземете и с определени ключове на Pandoc да конвертирате вашия Markdown формат в желания вид на MS Word. Затова обикновено, след конвертиране, се налага да „доразвивате“ полученото .docx ръчно, което отново може да бъде времеемко и да доведе до грешки.
Ако можехме да напишем скрипт, който автоматично да „доправя“ това, с което Pandoc не е успял — това би било идеално решение.
Поради неидентичността на функционалността на MS Word и Markdown в общия случай, решаването на тази задача, мисля, е невъзможно, но може ли да бъде направено приложимо за конкретни ситуации и специфични изисквания? Моят опит показва, че да, възможно е и вероятно е приложимо за много, а може би дори за повечето ситуации.
Решаване на частен проблем
Така, в моя случай, след конвертиране на файла с помощта на Pandoc, ми се налагаше ръчно да правя допълнителна обработка на файловете, а именно
- да добавя в Word полета с автоматична номериране на заглавията (caption) на таблиците и картинките
- да променя стила на таблиците
Не намерих как да направя това със стандартни (Pandoc) или известни средства. Затова използвах Python скрипт с пакет. В резултат получих пълна автоматизация. Сега мога да конвертирам Markdown файла си в необходимата форма на MS Word документ с една команда.
Вижте детайлите .
Забележка
В този пример, разбира се, преобразувам съществувал Markdown файл, но точно същият подход беше приложен и към «бойния» документ, и на изхода получих почти същия MS Word документ, който преди получавахме чрез ръчно форматиране.
Обобщено, с pywin32 получаваме почти пълен контрол над MS Word документа, което позволява да го променяме и да го приведем до вида, изискван от корпоративния ви стандарт. Разбира се, същите цели можеха да бъдат постигнати и с помощта на други инструменти, например VBA макроси, но аз предпочитах да използвам python.
Кратката формула на този подход е:
Markdown + Git -- (нещо) --> MS WordНе е толкова важно какво представлява «нещо». В моя случай това беше Pandoc и python с pywin32. Вероятно имате свои предпочитания, но важното е, че това е възможно. И именно това е основното послание на тази статия.
В обобщение, идеята е, че при този подход работите само с Markdown файл и използвате Git за организиране на съвместна работа и контрол на версиите, и само при необходимост (например, за да предоставите документация на клиента) автоматично създавате файл в нужния формат (например, MS Word).
Процесс
Мисля, че за много хора формулата, представена по-горе, е достатъчна, за да разберат как може да бъде организиран процесът на работа с документация сега. Но все пак обикновено се ориентирам към мрежови инженери, така че в общи линии ще покажа как би изглеждал процесът сега и с какво се различава от подхода с редактиране на MS Word файлове.
За яснота, ще изберем GitHub като платформа за работа с Git. Тогава трябва да създадете репозиторий и в master клон да поставите Markdown файл или файлове, с които планирате да работите.
Ще разгледаме прост процес, основан на «github flow». Неговото описание може да бъде намерено както в интернет, така и на .
Да предположим, че по документацията работят четирима души и вие сте един от тях. Тогава се създават четири допълнителни клона (branch), например, с имената на тези хора. Всеки работи локално, в своя клон и прави изменения с всички необходими .
След като завършите определен фрагмент от работата, вие създавате pull request, което инициира обсъждане на вашите промени. Възможно е в процеса на обсъждане да се установи, че трябва да добавите или промените нещо. В такъв случай вие правите необходимите изменения и създавате допълнителен pull request. В крайна сметка вашите промени се приемат и сливат (merge) с основната клонка (master) или се отхвърлят.
Разбира се, това е доста общо описание. Предлагам за създаване на подробен процес да се обърнете към вашите разработчици или да намерите запознати лица. Но искам да подчертая, че входната бариера за Git е доста ниска. Това не означава, че протоколът е прост, но можете да започнете с нещо елементарно. Ако не знаете абсолютно нищо, мисля, че следвайки няколко часа или може би дни за изучаване и инсталиране, можете да започнете да го използвате.
Каква полза носи този подход в сравнение с процеса, описан в примера по-горе?
Всъщност процесите са доста подобни, просто вие сте заменили
копиране на файл -> създаване на клон (branch)
копиране на текст в крайния файл -> сливане (merge)
копиране на последните изменения към себе си -> git pull/fetch
обсъждане в кореспонденция -> pull requests
режим на проследяване -> git diff
последна одобрена версия -> основен клон
бекъп (копиране на отдалечен сървър) -> git push
…
По този начин автоматизирахте всичко онова, което иначе бихте правили ръчно.
На по-високо ниво това ви позволява
- да създадете ясен, прост и контролируем процес на изменения в документацията.
- Тъй като крайният документ (в нашия пример MS Word) се генерира автоматично,这是减少格式化错误的可能性。
Забележка
С оглед на горепосоченото, смятам, че е очевидно, че дори ако работите върху документацията сами, използването на Git може значително да улесни работата ви.
Всичко това повишава качеството на документацията и намалява времето за нейното създаване. И още един малък бонус — ще научите Git, което ще ви помогне при автоматизацията на вашата мрежа 🙂
Как да преминете на новия процес?
В началото на статията споменах, че още утре можете да започнете да работите по нов начин. Как да пренасочите работата си в нова посока?
Ето последователността от стъпки, която вероятно ще трябва да изпълните:
- ако вашият документ е много голям, разделете го на части.
- Конвертирайте всяка част в Markdown (например, с Pandoc)
- Инсталирайте един от редакторите на Markdown (аз използвам )
- вероятно ще трябва да коригирате форматирането на създадените Markdown документи
- започнете да прилагате процеса, описан в предишната глава
- паралелно започнете да модифицирате скрипта за конвертиране според вашите нужди (или създайте нещо собствено)
Не е необходимо да чакате, докато създадете и усъвършенствате механизма за конвертиране Markdown -> изисквания вид на документа. Става въпрос, че дори ако не успеете бързо да автоматизирате напълно процедурата по преобразуване на вашите Markdown файлове, все пак ще можете да я направите в някаква форма с помощта на Pandoc и след това да доведете до окончателния вид ръчно. Обикновено не е нужно да правите това често, а само в края на определени етапи, и тази ръчна работа, макар и неудобна, все пак е напълно приемлива на етапа на отстраняване на грешки и не трябва да забавя процеса.
Всичко останало (Markdown, Git, Pandoc, Typora) вече е готово и не изисква специални усилия или време, за да започнете да работите с тях.
Източник: habr.com
