Понякога не само документацията, но и процесът на работа с нея може да бъде критичен. Например, в случай на проекти, голяма част от работата е свързана именно с подготовката на документацията, а неправилният процес може да доведе до грешки и дори до загуба на информация, а следователно и до загуба на време и полза. Но дори и ако тази тема не е централна във вашата работа и е на периферията, правилният процес все пак може да подобри качеството на документа и да ви спести време.
Предложеният тук подход, с , има нисък праг на влизане. Технологично, вече утре можете да започнете да работите по нов начин.
Формулиране на задачата
Трябва да създадете някакъв документ или набор от документи. Вероятно става дума за проектна документация или протоколиране на вашата мрежа, или нещо по-просто, като например трябва да опишете процесите в компанията или в отдела си. Също така, става дума за всеки документ или набор от документи с текст, снимки, таблици... Усложняваме задачата, като
- тази работа предполага съвместен труд, усилия на група или няколко групи служители
- в крайна сметка искате да имате документ в определен формат, с атрибути на корпоративен стил, създаден по определен шаблон. За определеност ще приемем, че това е 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. Не можете просто да вземете вашия Markdown формат и да го конвертирате в желания вид MS Word с определени ключове на Pandoc. Така че обикновено, след конвертирането, трябва да "доработвате" получения .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.
За яснота, за платформа за работа с Git ще изберем GitHub. Тогава трябва да създадете репозитория и в основния клон да поставите Markdown файла или файловете, с които планирате да работите.
Ще разгледаме прост процес, основан на „github flow“. Неговото описание може да бъде намерено както в интернет, така и на .
Да предположим, че по документацията работят четирима души и вие сте един от тях. Тогава се създават четири допълнителни клонове (branch), например с имената на тези хора. Всеки работи локално, в своя клон и прави промени с всички необходими .
Извършвайки завършена част от работата, вие формулирате pull request, инициирайки по този начин обсъждане на вашите промени. В процеса на обсъждането може да се установи, че трябва да добавите или промените нещо друго. В такъв случай вие правите необходимите промени и създавате допълнителен pull request. В крайна сметка, вашите промени се приемат и се сливам (merge) с master клон (или се отхвърлят).
Разбира се, това е доста общо описание. Предлагам за създаването на детайлен процес да се обърнете към вашите разработчици или да намерите запознати хора. Но искам да подчертая, че прага на влизане в Git е доста нисък. Това не означава, че протоколът е прост, но можете да започнете с основите. Ако не знаете нищо, мисля, че след като прекарате няколко часа или дори дни в учене и настройка, можете да започнете да го използвате.
Каква е ползата от този подход в сравнение, например, с процеса, описан в примера по-горе?
Всъщност процесите са доста сходни, просто сте заменили
копиране на файл -> създаване на клон (branch)
копиране на текст в крайния файл -> сливане (merge)
копиране на последните промени към вас -> git pull/fetch
обсъждане в кореспонденция -> pull requests
track mode -> git diff
последната одобрена версия -> master клон
бекъп (копиране на отдалечен сървър) -> git push
…
По този начин автоматизирахте всичко, което вие и без това трябваше да правите ръчно.
На по-високо ниво това ви позволява
- да създадете ясен, прост и контролируем процес на промени в документацията
- тъй като крайният документ (в нашия пример MS Word) създавате автоматично, това намалява вероятността от грешки, свързани с форматирането
Бележка
С оглед на казаното по-горе, мисля, че е очевидно, че дори ако работите над документацията сами, използването на Git може значително да улесни вашата работа.
Всичко това повишава качеството на документацията и намалява времето за създаването ѝ. И още една малка добавка — ще изучите Git, което ще ви помогне при автоматизацията на вашата мрежа 🙂
Как да преминете на нов процес?
В началото на статията написах, че още утре можете да започнете да работите по нов начин. Как да насочите вашата работа в нова посока?
Ето последователността от стъпки, които вероятно ще трябва да изпълните:
- ако вашият документ е много голям, разделете го на части
- конвертирайте всяка част в Markdown (с помощта на Pandoc, например)
- инсталирайте един от редакторите на Markdown (аз използвам )
- вероятно ще трябва да коригирате форматирането на създадените Markdown документи
- започнете да прилагате процеса, описан в предишната глава
- паралелно започнете да изменяте скрипта за конвертиране според вашата задача (или създайте нещо свое)
Не е необходимо да чакате, докато създадете и отладите перфектно механизма за конвертиране от Markdown до изисквания вид на документа. Истината е, че, дори и да не успеете бързо да автоматизирате процедурата за преобразуване на вашите Markdown файлове, вие все пак можете да го направите в някакъв вид с помощта на Pandoc и после да го доведете до крайния вид ръчно. Обикновено не е нужно да правите това често, а само в края на определени етапи, и тази ръчна работа, макар и неудобна, е напълно приемлива на етапа на отладка и не трябва да „забавя“ процеса.
Всичко останало (Markdown, Git, Pandoc, Typora) вече е готово и не изисква специални усилия или време, за да започнете да работите с тях.
Източник: habr.com
