Иногда важно не только содержание документации, но и процесс ее подготовки. В некоторых проектах с этим процессом связана львиная доля работы, а его нарушения могут приводить к ошибкам, утрате информации и в конечном итоге к временным и финансовым потерям. И даже если обозначенная тема не является вашей основной задачей, правильная организация этого процесса поможет вам улучшить качество документации и сэкономить время.
Метод, описанный ниже, отличается низким порогом вхождения: фактически уже завтра вы сможете начать работать по-новому.
Такой подход все еще актуален — даже крупные интеграторы используют его при создании проектной документации. Однако интуитивно понятно, что он не очень удобен, если работа над документом занимает много времени и включает множество правок и обсуждений.
Когда мы перешли к предварительному тестированию, начали возникать проблемы. И хотя они были небольшими, нам приходилось постоянно вносить изменения в документацию. Каждый день четыре разные команды практически в одно и то же время занимались внесением правок, сопровождая этот процесс обсуждениями. Все изменения проходили через согласование с единственным инженером — архитектором. Поскольку файл проектного решения был огромным, наш архитектор оказался перегружен механической работой — копированием и правкой. Он делал много ошибок. Нам приходилось все перепроверять и отправлять назад. Рабочий процесс превратился в полный хаос.
Итак, работа с документацией на основе MS Word давалась нам с большим трудом, поэтому такой подход создавал проблемы.
Я заметил, что люди все чаще используют при создании документов язык разметки Markdown в сочетании с системой управления версиями Git.
Вообще Git — это инструмент разработки. Но почему бы не использовать его и для подготовки документации? В этом случае проблема с одновременной работой нескольких пользователей будет решена. Лучше всего преимущества Git раскрываются в работе с документами на основе обычного текста, поэтому вместо MS Word нам придется использовать другой инструмент. 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, я думаю, что эту проблему невозможно решить в целом. Но возможно ли сделать это в контексте определенных ситуаций и требований? Мой опыт показывает, что возможно, — причем во многих, а то и в большинстве ситуаций.
За счет pywin32 можно получить практически полный контроль над документом MS Word, что позволяет привести его к тому виду, которого требует корпоративный стандарт. Конечно, этого результата можно добиться и с помощью других инструментов — например, макросов на VBA, — но мне было удобнее использовать Python.
Вот короткая формула этого подхода:
Markdown + Git − (нечто) → MS Word
На месте этого «нечто» может быть что угодно. В моем случае это были Pandoc и скрипт на Python, работающий с пакетом pywin32. У вас могут быть другие предпочтения. Важно одно — формула работает. Это основная мысль всей статьи.
Если коротко, идея такого подхода заключается в том, чтобы работать только с файлами Markdown, используя Git для взаимодействия с другими участниками проекта и управления версиями. При необходимости (например, если нужно предоставить документацию клиенту) можно автоматически создать файл желаемого формата (скажем, MS Word).
Возьмем GitHub в качестве рабочей платформы для Git. Необходимо создать репозиторий и добавить в главную ветку файл или файлы Markdown, с которыми вы собираетесь работать.
Допустим, подготовкой документации занимаются четыре человека, и вы один из них. Тогда нужно создать четыре дополнительные ветки — например, с именами участников. Каждый из них будет работать локально, в собственной ветке, используя все необходимые команды Git.
Завершив какую-то часть работы, вы создадите pull-запрос, чтобы начать обсуждение предлагаемых изменений с другими участниками. Возможно, в процессе выяснится, что вам нужно добавить или поменять что-то еще. В таком случае вы внесете необходимые правки и создадите еще один pull-запрос. В конечном итоге ваши изменения будут объединены с главной веткой (или отвергнуты).
Конечно, это довольно общее описание. Для создания детально проработанного процесса рекомендую подключить к делу разработчиков или найти специалистов с опытом в этой области. Но я хотел бы заметить, что у системы Git довольно низкий порог вхождения. Хотя принцип функционирования системы не так прост, с ней легко начать работать. Я думаю, что, даже если вы столкнетесь с ней впервые, вы сможете начать ее использовать, потратив несколько часов или дней на изучение и установку.
В чем преимущество этого подхода перед процессом из примера выше?
На самом деле, они довольно схожи, просто одни понятия заменяются другими:
На более высоком уровне это позволит:
Вот наиболее вероятная последовательность шагов:
Остальные инструменты (Markdown, Git, Pandoc, Typora) уже готовы к использованию и не требуют много сил или времени на освоение.
Источник статьи: https://habr.com/ru/company/otus/blog/568726/
Метод, описанный ниже, отличается низким порогом вхождения: фактически уже завтра вы сможете начать работать по-новому.
Постановка задачи
Итак, вам нужно создать один или несколько документов. Возможно, это проектная документация, выдержки из сетевых логов или что-то более простое. Допустим, вы хотите описать процессы, происходящие в компании или в вашем отделе. Такие документы обычно содержат текст, рисунки, таблицы и т. д. Усложним задачу, добавив следующие условия:- Работа над документом требует совместных усилий нескольких сотрудников или даже нескольких групп.
- В результате должен получиться документ определенного формата, созданный по шаблону и содержащий элементы фирменного стиля. Для большей конкретики возьмем формат MS Word (.docx).
Такой подход все еще актуален — даже крупные интеграторы используют его при создании проектной документации. Однако интуитивно понятно, что он не очень удобен, если работа над документом занимает много времени и включает множество правок и обсуждений.
Пример
Я впервые столкнулся с этой проблемой, работая с одним крупным интегратором. Процесс внесения правок в проектную документацию у нас выглядел так:- Инженер загружает последнюю версию документа MS Word (.docx)
- Меняет название документа
- Вносит правки в режиме отслеживания изменений
- Отправляет документ с правками архитектору
- Также прикладывает список всех изменений с комментариями
- Архитектор анализирует изменения
- Если все в порядке, он вносит эти правки в последнюю версию файла, меняет номер версии и загружает документ на общий ресурс
- Если же у архитектора появляются замечания, начинается их обсуждение (по электронной почте или на собраниях)
- Наконец, все участники процесса приходят к единому мнению
- Повторяются шаги с 3-го по 9-й
Когда мы перешли к предварительному тестированию, начали возникать проблемы. И хотя они были небольшими, нам приходилось постоянно вносить изменения в документацию. Каждый день четыре разные команды практически в одно и то же время занимались внесением правок, сопровождая этот процесс обсуждениями. Все изменения проходили через согласование с единственным инженером — архитектором. Поскольку файл проектного решения был огромным, наш архитектор оказался перегружен механической работой — копированием и правкой. Он делал много ошибок. Нам приходилось все перепроверять и отправлять назад. Рабочий процесс превратился в полный хаос.
Итак, работа с документацией на основе MS Word давалась нам с большим трудом, поэтому такой подход создавал проблемы.
Git и Markdown
Столкнувшись с проблемой, описанной выше, я решил исследовать этот вопрос.Я заметил, что люди все чаще используют при создании документов язык разметки Markdown в сочетании с системой управления версиями Git.
Вообще Git — это инструмент разработки. Но почему бы не использовать его и для подготовки документации? В этом случае проблема с одновременной работой нескольких пользователей будет решена. Лучше всего преимущества Git раскрываются в работе с документами на основе обычного текста, поэтому вместо MS Word нам придется использовать другой инструмент. 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 для автоматической нумерации таблиц и рисунков;
- Менять стили таблиц.
За счет pywin32 можно получить практически полный контроль над документом MS Word, что позволяет привести его к тому виду, которого требует корпоративный стандарт. Конечно, этого результата можно добиться и с помощью других инструментов — например, макросов на VBA, — но мне было удобнее использовать Python.
Вот короткая формула этого подхода:
Markdown + Git − (нечто) → MS Word
На месте этого «нечто» может быть что угодно. В моем случае это были Pandoc и скрипт на Python, работающий с пакетом pywin32. У вас могут быть другие предпочтения. Важно одно — формула работает. Это основная мысль всей статьи.
Если коротко, идея такого подхода заключается в том, чтобы работать только с файлами Markdown, используя Git для взаимодействия с другими участниками проекта и управления версиями. При необходимости (например, если нужно предоставить документацию клиенту) можно автоматически создать файл желаемого формата (скажем, MS Word).
Процесс
Думаю, многим читателям будет достаточно приведенной выше формулы, чтобы понять, как можно организовать работу с документацией. Но я все же обычно ориентируюсь на сетевых инженеров, поэтому в общих чертах расскажу, как может выглядеть рабочий процесс и чем он отличается от внесения правок в файлы MS Word.Возьмем GitHub в качестве рабочей платформы для Git. Необходимо создать репозиторий и добавить в главную ветку файл или файлы Markdown, с которыми вы собираетесь работать.
Допустим, подготовкой документации занимаются четыре человека, и вы один из них. Тогда нужно создать четыре дополнительные ветки — например, с именами участников. Каждый из них будет работать локально, в собственной ветке, используя все необходимые команды Git.
Завершив какую-то часть работы, вы создадите pull-запрос, чтобы начать обсуждение предлагаемых изменений с другими участниками. Возможно, в процессе выяснится, что вам нужно добавить или поменять что-то еще. В таком случае вы внесете необходимые правки и создадите еще один pull-запрос. В конечном итоге ваши изменения будут объединены с главной веткой (или отвергнуты).
Конечно, это довольно общее описание. Для создания детально проработанного процесса рекомендую подключить к делу разработчиков или найти специалистов с опытом в этой области. Но я хотел бы заметить, что у системы Git довольно низкий порог вхождения. Хотя принцип функционирования системы не так прост, с ней легко начать работать. Я думаю, что, даже если вы столкнетесь с ней впервые, вы сможете начать ее использовать, потратив несколько часов или дней на изучение и установку.
В чем преимущество этого подхода перед процессом из примера выше?
На самом деле, они довольно схожи, просто одни понятия заменяются другими:
- Копировать файл → создать ветку (branch)
- Копировать текст в целевой файл → выполнить слияние (merge)
- Копировать последние изменения к себе → git pull/fetch
- Обсуждение в чате → pull-запросы
- Режим отслеживания изменений → git diff
- Последняя утвержденная версия → главная ветка (master)
- Резервное копирование (создание копии на удаленном сервере) → git push
На более высоком уровне это позволит:
- Создать четкий, простой и управляемый процесс внесения правок в документы
- Снизить риск возникновения ошибок, связанных с форматированием, поскольку итоговый документ (в нашем случае документ MS Word) создается автоматически
Как запустить новый процесс?
В начале статьи я упомянул, что начать работать по-новому вы сможете уже завтра. Как это сделать?Вот наиболее вероятная последовательность шагов:
- Если документ слишком большой, разделите его на части
- Конвертируйте каждую из них в формат Markdown (например, с помощью Pandoc)
- Установите редактор Markdown (я использую Typora)
- Скорее всего, вам придется поправить полученные документы Markdown
- Следуйте инструкциям, описанным в предыдущей части
- Начните изменять скрипт конвертации для вашей задачи (или создайте свой собственный)
Остальные инструменты (Markdown, Git, Pandoc, Typora) уже готовы к использованию и не требуют много сил или времени на освоение.
Источник статьи: https://habr.com/ru/company/otus/blog/568726/