Изложенный здесь подход, с примером конкретной реализации, имеет низкий порог вхождения. Технически, уже завтра вы можете начать работать по-новому.
Постановка задачи
Вам нужно создать некий документ или набор документов. Возможно, это проектная документация или протоколирование вашей сети, или что-то более простое, например, вы должны описать процессы в компании или в вашем отделе. В общем, речь идет о любом документе или наборе документов с текстом, картинками, табличками… Усложним задачу тем, что
- данная работа предполагает совместный труд, усилия группы или нескольких групп сотрудников
- на выходе вы хотите иметь документ в определенном формате, с атрибутами корпоративного стиля, созданный по определенному шаблону. Для определенности мы будем считать, что это MS Word (.docx)
10 лет назад подход был бы однозначным: мы бы создали MS Word документ или документы и каким-либо образом организовали бы работу по изменению.
И такой подход по-прежнему в силе. Им пользуются в том числе и крупные интеграторы при создании проектной документации. Но интуитивно понятно, что, если вы действительно интенсивно, со многими правками и обсуждениями, в течении продолжительного времени работаете над документом данный подход не очень удобен.
Пример
Я довольно остро ощутил эту проблему, работая в одном крупном интеграторе. Процесс изменения проектной документации был следующий:
- инженер скачивает последнюю версию MS Word (.docx) документа
- меняет название
- вносит правки в track моде
- отсылает документ с правками архитектору
- так же отсылает перечень всех исправлений с комментариями
- архитектор анализирует изменения
- если все хорошо, то копирует данные изменения в файл с последней версией, меняет версию, выкладывает на общий ресурс
- если есть замечания, то инициируется обсуждение (email или митинги)
- достигается консенсус
- далее пункты 3 — 9
Пока работа не была интенсивной, то это кое-как, но все же работало. Но в определенный момент этот процесс стал узким местом целого проекта и привел к проблемам. Дело в том, что все становится плохо, как только изменения производятся часто и одновременно несколькими командами.
Так, когда мы перешли на стадию предварительного тестирования, то начали проявляться разные проблемки и, хотя и по мелочам, но нужно было часто менять документацию — четыре разные команды, ежедневно, практически одновременно, с обсуждениями. Все эти изменения проходили через одного инженера — архитектора. Файл с дизайном проекта был огромный, и как следствие, архитектор был завален рутинной работой, связанной с большим количеством копирования, редактирования, делал много ошибок, приходилось все перепроверять, перепосылать, и в общем это было близко к хаосу.
В данном случае этот подход, подход работы над документом MS Word, работал с большим скрипом и создавал проблемы.
Git, Markdown
Столкнувшись с проблемой, описанной в примере выше, я стал исследовать этот вопрос.
Я увидел, что все более становится популярным использование Markdown совместно с Git при создании документов.
Git — это инструмент для разработки. Но почему бы его не использовать для процесса документирования? В этом случае вопрос многопользовательской работы становится решенным. Но для того, чтобы в полной мере использовать возможности Git нам нужен текстовый формат документа, нам нужно найти другой инструмент, не MS Word, и для этих целей отлично подходит Markdown.
Markdown — простой язык текстовой разметки. Он предназначен для создания красиво оформленных текстов в обычных файлах формата TXT. Если мы будем создавать наши документы в Markdown, то связка Markdown — Git выглядит естественной.
И все бы хорошо, и в этом месте можно было бы поставить точку, если бы не наше второе условие: «на выходе нам нужен документ в определенном формате, с атрибутами корпоративного стиля, созданный по определенному шаблону» (и мы договорились вначале, что для определенности это будет MS Word). То есть, если мы решили использовать Markdown, то нам нужно как-то преобразовать этот файл в .docx требуемого вида.
Существуют программы конвертации между различными форматами, например, Pandoc.
Вы можете конвертировать Markdown файл в .docx формат с этой программой.
Но все же, надо понимать, что, во-первых, не все, что есть в Markdown будет конвертировано в MS Word и, во-вторых, MS Word — это целая страна по сравнению со стройным, но все же городком, Markdown. Есть огромное количество всего, что есть в Word и ни в каком виде нет в Markdown. Нельзя просто так вот взять и с определенными ключами Pandoc конвертировать ваш Markdown формат в желанный вид MS Word. Так что обычно, после конвертации, приходится «дорабатывать» полученный .docx документ вручную, что опять-таки может быть затратным с точки зрения времени и приводить к ошибкам.
Если бы мы могли написать скрипт, который автоматически «доделывал» бы то, с чем не справился Pandoc — это было бы идеальное решение.
В силу не тождественности функционала MS Word и Markdown в общем виде решить эту задачу, думаю, невозможно, но можно ли это сделать применительно к конкретным ситуациям, конкретным требованиям? Мой опыт показал, что да, можно и скорее всего это возможно для многих, или может быть даже большинства ситуаций.
Решение частной задачи
Так, в моем случае, после конвертации файла с помощью Pandoc, мне приходилось вручную делать дополнительную обработку файлов, а именно
- добавлять в Word поля с автоматической нумерацией заголовков (caption) таблиц и картинок
- менять стиль для таблиц
Я не нашел, как это сделать стандартными (Pandoc) или известными средствами. Поэтому я применил python скрипт с pywin32 пакетом. В результате я получил полную автоматизацию. Теперь я могу конвертировать мой Markdown файл в нужную форму MS Word документа одной командой.
Смотрите детали здесь.
Замечание
В этом примере я, конечно же, преобразую некий абстрактный Markdown файл, но в точности тот же подход был применен к «боевому» документу, и на выходе я получил практически точно тот же MS Word документ, который до этого мы получали ручным форматированием.
В общем, c pywin32 мы получаем практически полный контроль над MS Word документом, что позволяет менять его, и приводить к виду, который требует ваш корпоративный стандарт. Конечно, этих же целей можно было добиться и с использование других инструментов, например, VBA макросов, но мне было удобней использовать python.
Краткая формула данного подхода:
Markdown + Git -- (нечто) --> MS WordНе так важно, чем является «нечто». В моем случае это был Pandoc и python с pywin32. Возможно, у вас другие предпочтения, но важно то, что это возможно. И это и есть главный посыл этой статьи.
Резюмируя, идея в том, что при таком подходе вы работаете только с Markdown файлом и пользуетесь Git для организации совместной работы и для контроля версий, и только при необходимости (например, чтобы предоставить документацию клиенту) автоматически создаете файл нужного формата (например, MS Word).
Процесс
Думаю, для многих формула, приведенная выше достаточна, чтобы понять, как теперь может быть организован процесс работы с документацией. Но все же я обычно ориентируюсь на сетевых инженеров, поэтому в общих чертах покажу, как теперь может выглядеть процесс работы, и чем это отличается от подхода с редактированием MS Word файлов.
Для определенности, в качестве платформы для работы с Git выберем GitHub. Тогда вы должны создать репозиторий и в master ветке поместить Markdown файл или файлы, с которыми планируете работать.
Мы рассмотрим простой процесс, основанный на «github flow». Его описание можно найти, как в интернете, так и на хабре.
Предположим, что над документацией работают четыре человека и вы — один из них. Тогда создаются четыре дополнительные ветки (branch), например, с именами этих людей. Каждый работает локально, в своей ветке и делает изменения со всеми необходимыми git командами.
Выполнив какой-то законченный кусок работы, вы формируете 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 (я пользуюсь Typora)
- скорее всего вам придется подправить форматирование созданных Markdown документов
- начинайте применять процесс, описанный в предыдущей главе
- параллельно начинайте видоизменять скрипт конвертации под свою задачу (или создайте что-то свое)
Вам не обязательно ждать, когда вы создадите и отладите в совершенстве механизм конвертации Markdwon -> требуемый на выходе вид документа. Дело в том, что, даже если вам не удастся быстро полностью автоматизировать процедуру преобразования ваших Markdown файлов, вы все равно сможете это сделать в каком-либо виде с помощью Pandoc и далее довести до конечного вида вручную. Обычно вам не нужно это делать часто, а только в конце определенных этапов, и эта ручная работа, хоть и неудобна, но все же, на мой взгляд, вполне допустима на этапе отладки и не должна сильно «тормозить» процесс.
Все остальное (Markdown, Git, Pandoc, Typora) уже готово и не требует особых усилий или времени для того, чтобы начать работать с ними.
Комментарии (30)
A114n
17.06.2019 16:35Может быть мы здесь наблюдаем ситуацию, когда людям удобнее пользоваться привычным инструментом, чем инструментом специальным — «чуточку заточат топор и бреются им по воскресеньям»©.
Ведь есть превеликое множество различных способов совместного онлайн-редактрования, начиная от того же Word в режиме совместной работы и заканчивая гугл-документами.nihole Автор
17.06.2019 16:39Не решаются все проблемы просто возможностью совместного редактирования.
Flaminestone
17.06.2019 16:53+1Если вам нужно создавать документы со сложным форматированием, то markdown, наверное, это не самый удачный вариант. Добавление и правка таблиц в md это вообще отдельное искусство, требующее терпения. А если использовать комбинацию картинок (которые, к слову, не содержатся в md) и таблиц, то документ потеряет всякую наглядность. Или вы не используете таблицы в документации?
И если основная проблема работы через MS Word была в том, что нет возможности работать совмесно, то можно посмотреть в сторону редакторов документов, которые позволяют это делать.
Надеюсь, это не прозвучит как реклама, но если вам нужно совмесное редактирование + контроль версий + рецензирования документов, то в редакторах ONLYOFFICE все это есть.nihole Автор
17.06.2019 16:58Спасибо, посмотрю.
Таблицы, конечно, требуются, но функциональности Markdown оказалось достаточно.
KvanTTT
17.06.2019 19:58Попруйте плагин для форматирования таблиц под VS Code Table Formatter. Для создания, наверное, тоже есть.
KvanTTT
18.06.2019 12:57Добавление и правка таблиц в md это вообще отдельное искусство, требующее терпения.
А разве нельзя использовать обычный html синтаксис для таблиц и других сложных элементов? Markdown поддерживает его внутри себя.
Flaminestone
18.06.2019 13:35Можно конечно, но смысл тогда от markdown? Почему бы все не сделать в html, и открывать в браузере. Прикрутить стили, списки, навигацию, будет похоже на wiki.
Я не утрирую, а правда считаю что будет довольно удобно.
Проблема в том, что исходный код такой страницы сильно проигрывает в наглядности маркдауну. И потому, если нужно будет что-то править, то придется немного покопаться в коде.
Markdown как раз хорош тем, что его можно открыть любым редактором текста, и все равно все будет понятно. Стоит ли жертвовать этим ради необходимых сложных элементов? Вопрос открытый.
KvanTTT
18.06.2019 13:54Смысл такой, что markdown намного наглядней и проще HTML, за исключением таблиц. Лично у меня с таблицами особых пробелем нет, но я предложил парочку решений как можно облечить жизнь с ними: плагин или HTML. Можно ли придумать синтаксис для таблиц, чтобы он был удобный и с точки зрения дифов и с точки зрения редактирования? Вопрос открытый.
dburmistrov
17.06.2019 17:15+1Мы остановились на reStructuredText, он по-богаче Markdown, но не такой сложный, как LaTeX. Публикация в html и confluence
skymal4ik
17.06.2019 21:14+1Если нету требования иметь именно word на выходе, то можно конвертировать md сразу в pdf. Такое и печатать, и клиенту передать удобно.
Pandoc умеет и toc, и нумерацию страниц, и титульную страницу.
На просторах интернета также есть классные темплейты для pdf.nihole Автор
17.06.2019 22:39Радуют комментарии. Много конструктивных дополнений. Не так просто все это найти самому.
Спасибо всем!
raydac
18.06.2019 00:25маркдаун удобный формат так как текстовый из-за чего хорошо совместим с CVS системами, удобно прямо в проекте держать, но мне было маловато и я себе сделал что бы маркдаун в виде майнд мапы хранился с возможностью конвертирования и при помощи плагина рендерю
DmitryMironov
18.06.2019 08:17А почему не стали использовать Wiki, например Atlassian Confluence?
Из того что вам нужно, там все есть.KvanTTT
18.06.2019 09:54+1Из недостатков:
- Ограниченная история, только линейная. В Git же можно как угодно бранчеваться и вертеть историей.
- Невозможность редактирования файлов локально в любом редакторе (только веб).
Из достоинств:
- Удобный WYSIWYG редактор – можно редактировать и создавать странице даже не разбираясь в синтаксисе разметке (как в Word).
- Скорее всего хорошая интеграция с другими сервисами Atlassian (Jira, BitBucket).
SignallerK
18.06.2019 12:28+1В новом проекте как раз используем конфлюенс, все так и есть. По недостаткам добавил бы:
- Невозможно как-то связать историю «дерева», например если док состоит из нескольких страниц confluence под одним рутом, то не возможно их как-то синхронизировано откатить на «предыдущий релиз»
- Хромающая на 2 ноги работа с таблицами, особенно при выводе в тот же ворд. (Впрочем автору тут и git не особо помошник).
Из плюсов:
- Довольно большое количество плагинов как из коробки, так и то что можно добавить самому. Так что возможно сделать довольно гибкий функционал кросс-ссылок, дабы отследить в каком тикете Jira возник запрос на фичу (которую описавает дока), и в каком ее имлементировали и тд.
paul77
18.06.2019 13:01А в чем проблема использования Word редактора с хранением данных в GIT? Мы использовали SVN + Word в первую очередь для интеграции в систему управления задачами (линковка через коммент в commit на номер задачи). Средствами Word можно сравнивать две версии документа и объединять изменения в новую версию документа.
KvanTTT
18.06.2019 13:59+1Вот именно что только средствами Word, да и то довольно ограниченно. Git работает на всех операционных системах, под него существует множество клиентов. Думаю не надо подробно расписывать возможности системы контроля, среди которых ветвление, версионирование, изменение истории.
А поддерживает ли Word относительные ссылки? Т.е. чтобы можно было указывать URL картинки в виде
[image name](../image.jpg). Markdown поддерживает.paul77
18.06.2019 14:23А для каких целей это требуется? Обычно хватало абсолютных ссылок начиная с корня хранилища. Так же для изображений можно использовать их встраивание в Word документ. Если в данной статье упоминается Word как целевой формат, очень много сложностей для конвертаций в обе стороны.
KvanTTT
18.06.2019 15:35А для каких целей это требуется?
Хранить картинки отдельно от статьи, а также возможность их независимого редактирования. По сути несколько страниц маркдауна вместе с картинками — это уже статичный сайт или блог.
Обычно хватало абсолютных ссылок начиная с корня хранилища.
Они должны быть инвариантными относительно файловой системы отдельно взятого пользователя. Абсолютные ссылки относительно корня хранилища в моем понимании уже относительные.
nihole Автор
18.06.2019 16:57Прежде всего уверен (и комментарии это подтверждают), что существуют разные способы решения этой задачи. Если вы нашли свой подход, и он удобен для вас, то отлично.
В-вторых, сложно сравнивать методы. Я знаю детально сильные стороны изложенного мной подхода (слабые тоже), но не могу сказать, что осознаю до конца, что предлагаете вы. Поэтому могу говорить только какие-то общие вещи, а именно
1) подход с markdown выглядит более универсальным — вы можете конвертировать не только в Word, но и в другие форматы
2) лично для меня markdown очень удобен — в Word слишком много всего, и все должны делать это в едином стиле…
3) мне нравится разделение функций — Git отвечает за многопользовательскую работу, за версионирование и все что с этим связано, а Markdown — это информационная часть. В вашем же подходе, какие-то функции Git приходится делать силами Word и я не уверен, что там все это реализовано так же удобно
Но, еще раз хочу сказать, что описанный подход я не воспринимаю как лечение от всех болезней
totaki
18.06.2019 16:39+1В markdown+git я вижу такие преимущества.
- Документацию можно положить рядом с кодом, по моему мнению ему там и место.
- Изменение документации (при нормальном flow) привязывается к коду и коммиту которые его порадили
- Не требует дополнительного ПО, любой git SaaS умеет ренедерить Markdown
- Для редактирования не надо вылазить из привычного редактора (VSCode, IntelliJ)
- И главное это подсветка синтаксиса (если есть кто видел такую тулзу для google docs, скажите пожлайста)
nikolay_karelin
19.06.2019 22:55Есть еще AsciiDoc — насколько я слышал, O'Reily на нем свой процесс построили.
GavriKos
Сам недавно начал вести всю документацию в таком виде. Посоветовал бы обратить внимание на другие редакторы. Например — VSCode. Большое преимущество — в нем сразу есть Git.
nihole Автор
Да, спасибо, эта функция полезна!
may-cat
IntelliJ IDEA Community Edition. Нет ничего более удобного для работы с ветками, compare и мерджа. Особенно актуально это при работе с текстом (в котором нет жёсткого синтаксиса, как в коде).
GavriKos
ИМХО — сильно тяжелая штука для банального редактирования заметок. Но если устраивает — почему и нет :-)