Как мы искали замену MS Word, а вместо этого внедрили новый процесс управления документами

MS Word регулярно подкидывает нам «сюрпризы»: «съехавшие» скриншоты, «плывущие» таблицы, пустые страницы при печати. Эта статья о том, как мы искали замену MS Word, (спойлер — не нашли), а нашли возможность глобально улучшить наш процесс работы с документацией.

image

В Uniscan Research мы делаем наукоёмкие приборы серийным продуктом. Компания работает в секторе B2G (business-to-government) и B2C (business-to-client).

Наш отдел разрабатывает конструкторскую и пользовательскую документацию на разрабатываемые изделия, документы для сертификации, маркетинговые материалы, дизайн и оформление офиса (навигация, таблички на двери).

C документами в секторе B2C есть свобода выбора формата, названия и содержания документации. В секторе B2G около 70% документации, которую мы разрабатываем, должна быть оформлена в соответствии с требованиями ЕСКД и представлена на согласование заказчику в формате DOCX.

Пользователю мы передаем всю эксплуатационную документацию в напечатанном виде, поэтому все документы проходят предпечатную подготовку. Целевых форматов у наших документов два: DOCX и PDF.

Для выполнения наших задач в отделе традиционно в течение многих лет использовался MS Word.

При каждой новой правке свёрстанного в MS Word документа примерно в половине случаев «съезжают» скриншоты, «плывут» таблицы с иконками, а при печати документа и вовсе внезапно появляются невидимые пустые страницы. Эти операции по вёрстке документа отнимают у автора документа не только время, но и желание заниматься творчеством — разработкой новых документов.

Во время очередного поиска невидимых пустых страниц в документе DOCX в нашем отделе появилась идея попробовать новый инструмент разработки документации. Мы хотели сократить время на вёрстку и предпечатную подготовку документа.

В итоге нам так и не удалось полностью уйти от использования MS Word, но в процессе поисков мы построили новую схему работы с документацией.

Далее я постараюсь рассказать, какие инструменты для работы с документами мы рассматривали, почему в результате остановились на Confluence, с какими проблемами столкнулись и как смогли их решить.

Выбор инструмента


Мы почитали статьи на тему существующих инструментов по разработке документации, пообщались с коллегами из других компаний. Наиболее подходящими нам показались следующие инструменты:

  • Dita
  • DocBook XML
  • Confluence

Первые два инструмента не подошли по одной и той же причине: нам нужны были навыки программирования, которых у нас не было, а для создания нового шаблона документа пришлось бы звать на помощь программиста. Переход на работу с ними по нашим представлениям занял бы около полугода, возможно больше. Из-за перечисленных минусов мы решили отказаться от полноценного тестирования этих инструментов.

Confluence с самого начала порадовал WYSIWYG-редактором. В среднем техническим писателям потребовалось около недели на освоение инструмента, вёрстка документов «не по ГОСТу» давалась проще.

В B2G-проектах нам важен PDF как формат для пользовательской документации. Поэтому мы сразу установили соответствующий плагин для Confluence — Scroll PDF Exporter. С его помощью мы попробовали создать пользовательские шаблоны с необходимыми параметрами. Результатами тестирования остались довольны: один из документов с большим количеством скриншотов и графических элементов мы верстали в MS Word около недели; в Confluence тот же самый документ у нас получилось сверстать за 2 дня и добиться при этом лучшего визуального представления.

Ещё мы попытались настроить шаблон для Scroll Word Exporter таким образом, чтобы на выходе получить документ, оформленный по всем правилам ЕСКД. Спустя два дня чтения справочников Confluence и Scroll PDF Exporter и попыток настроить действующий шаблон технических условий, мы поняли, что этот инструмент не подходит для разработки документов, оформляемых в соответствии с требованиями ЕСКД.

Так, например, у нас не получилось сделать нумерованные нежирные заголовки второго уровня, чтобы текст был не заголовком, а абзацем. Приходилось вручную писать номер пункта и использовать стиль «абзац». Нельзя было оформить маркированные списки с тире (только круги, квадраты), нумерованные списки оформлялись без точки, а буквенные — только с латинскими буквами. Абзацные отступы настраивались только вручную.

Спустя несколько месяцев после того, как мы начали осваивать Confluence, разработчики инструмента реализовали функцию редактирования документов в их исходном формате. Это позволило нам хранить наши «гостовские» документы и создавать новые документы, не требующие строгого оформления, в одном и том же месте. Файлы MS Word хранятся в Confluence как вложения, при редактировании открываются и сохраняются в MS Word на ПК пользователя, а при сохранении новая версия автоматически заливается в Confluence.

Так у нас появилась идея использовать Confluence в качестве инструмента, который одновременно бы решал три задачи:

  1. Создание базы знаний.
  2. Разработка, хранение и актуализация документации, разрабатываемой не по ГОСТу.
  3. Хранение и актуализация документации, разрабатываемой по ГОСТу.

Потенциал Confluence


Наши ожидания от функционала Confluence оправдались не полностью, но после завершения тестирования сформировалось в целом положительное отношение к этому инструменту. Ниже мы сформулировали его основные плюсы для нашего отдела:

  1. Настройка и поддержка инструмента своими силами.
  2. Простота освоения.
  3. Возможность организовать базу знаний о продуктах компании и хранить всю свёрстанную документацию в DOCX и PDF в одном месте.
  4. Поддержка версионности документов.
  5. Возможность использования технологии единого источника.
  6. Возможность совместной работы разработчиков и технических писателей над документами.
  7. Хранение рабочих документов и информации в одном месте.
  8. Возможность разрабатывать документы в любое время из любой точки мира.

Внедрение


Для внедрения Confluence мы выделили из отдела технических писателей двух специалистов, которые изучали и тестировали возможности инструмента.
Для непрерывной технической поддержки отдел системных администраторов выделил нам одного специалиста. Он оперативно реагировал на технические проблемы и помогал разобраться с базовыми настройками нового инструмента.

В то же самое время мы создали в отделе технических писателей рабочую группу, задачей которой было планирование структуры хранения данных. Вся структура нашего сервера была разделена на категории, соответствующие типам проектов компании. Категории в свою очередь делились на пространства по продуктам компании. Мы также выделили отдельную категорию для внутренней базы знаний.

Когда ответственные за тестирование системы достаточно глубоко изучили работу в Confluence, начался этап взаимного обучения коллег. На передачу знаний всему отделу понадобилось около месяца.

Технические проблемы


Внедрение Confluence в целом проходило достаточно гладко, но были и проблемы.

Вёрстка и предпечатная подготовка документов


«Раньше я делал это в MS Word за пару секунд. Как сделать то же самое в Confluence?» — такой вопрос мы задавали себе каждый день в течение всего времени тестирования.

Так, было совсем неочевидно, как выровнять содержимое таблицы по вертикали или назначить иконке размер меньше 16 px.

Действительно, базовый набор функций форматирования страниц в WYSIWYG-редакторе Confluence в значительной степени проигрывает MS Word, однако функционал можно значительно расширить, если зайти в режим редактирования исходного кода и работать напрямую с HTML-кодом.

Мы читали статьи, смотрели обучающие видеоролики по HTML-вёрстке и обменивались найденными решениями. Мы создали отдельную страницу в Confluence, куда разместили полезную информацию по работе с этим инструментом.

image

Обновление версии Confluence и плагинов


После первого обновления основного плагина Scroll PDF Exporter слетело 80% макросов и поехала структура страниц в Confluence. Позже выяснилось, что случилось так из-за нового функционала плагина. Всем отделом мы восстанавливали структуру документов несколько дней. После этого мы составили план обновления на будущее, которого придерживаемся до сих пор:

  1. Проводите обновление в пятницу, когда выполнен основной пласт работ за неделю, чтобы иметь возможность устранить возможные проблемы на выходных.
  2. Сделайте рассылку всем пользователям системы, чтобы сообщить им о времени запланированного обновления.
  3. Перед обновлением выполните резервное копирование сервера.
  4. Обновите версию Confluence.
  5. Протестируйте сервер, убедитесь, что вся информация на месте, работают ссылки на внешние и внутренние ресурсы.
  6. При необходимости обновить плагины снова выполните резервное копирование сервера.
  7. Проводите обновление плагинов по принципу один плагин за раз.
  8. Тестируйте работу плагина сразу после обновления.

Массовые уведомления


Когда в Confluence наконец закипела бурная деятельность технических писателей и разработчиков, администратору посыпались звонки от пользователей сервиса. Они просили избавить их от массовой атаки почтовыми уведомлениями о действиях других пользователей.

По умолчанию пользователю нужно было всего лишь раз зайти на какую-нибудь страницу, после чего он автоматически добавлялся системой в список наблюдателей и получал уведомления при каждом изменении этой страницы.

Вдобавок к этому Confluence любезно делал еженедельную рассылку пользователям с перечислением самых популярных страниц Confluence. К счастью, эта проблема уже широко была освещена в интернете. Решение — отключить соответствующие уведомления в настройках системы:

image

Теперь пользователи получают уведомления, только если их имя упомянуто в комментариях к статье.

Стабильность сервера



image

Для тестирования Confluence мы развернули Windows-сервер. На первоначальных этапах сервер часто «падал». Часть проблемы оказалась в недостаточном объёме оперативной памяти на сервере (рекомендованный объём 11-12 ГБ). Оставшиеся проблемы ушли, когда мы включили рекомендованные в таких случаях настройки системы.

Сейчас сервер работает достаточно стабильно — нарушение в работе случаются примерно 1 раз в 2 месяца. В случае сбоя достаточно перезагрузки для его восстановления.

Управление документацией в Confluence


На сегодняшний день в Confluence совместно работают технические писатели, программисты, электронщики, QA.

Мы планировали полностью отказаться от MS Word, разрабатывать документы исключительно в Confluence и преобразовывать их в DOCX и PDF. В реальности оказалось, что можно обойтись без длительного процесса переноса всей существующей документации в новый формат и последующей настройки шаблонов в Scroll PDF/Word Exporter. По нашим оценкам нам потребовалось бы на это около полугода. Гораздо проще оказалось перенести все разработанные документы в формате MS Word в Confluence и поддерживать их там же.

Мы решили не ждать от Confluence чудесного форматирования по всем требованиям ЕСКД и просто разделили все пользовательские документы условно на документы для «госзаказчика» и документы для «не госзаказчика».

Первые мы создаём в формате DOCX, храним и актуализируем в Confluence. Вторые разрабатываем прямо в Confluence, экспортируем в PDF при необходимости.

Благодаря встроенным макросам мы используем технологию единого источника в пользовательской документации — теперь не приходится вручную менять один параметр в нескольких версиях документов.

Удобный WYSIWYG-редактор позволяет легче вносить изменения в готовый документ — скриншоты, иконки и графические элементы остаются на месте.

image

Функция совместного редактирования статей позволяет совместно работать над документом. Можно поделиться документом с техническим экспертом прямо в Confluence и обсуждать его замечания в реальном времени, а не перекидываться бесконечно документом по почте.

Для работы вне офиса не нужно настраивать удалённый доступ. Чтобы иметь возможность поработать из дома, нужен только интернет.

Confluence предлагает пользователю уже привычный всем интерфейс веб-страницы с возможностью настроить cross-ссылки и открыть в браузере для работы сразу несколько вкладок.

Теперь мы храним все документы, графические элементы, фото устройств, а также ведем базу знаний по продуктам компании в одном месте. Нет нужды думать, где могут лежать исходники рисунков или самая свежая версия документов.

Что ещё хочется сделать


В настоящий момент мы настраиваем процесс согласования страниц Confluence с помощью плагина Comala Workflow. Однако, этот плагин не работает с вложениями MS Word. Такие документы мы согласовываем с помощью комментариев к версиям. Сейчас мы рассматриваем варианты настройки автоматического согласования вложений DOCX. Хочется, чтобы процесс согласования и утверждения можно было одновременно использовать как со страницами Confluence, так и с вложениями формата DOCX.

Когда настроим автоматическое согласование вложений, попробуем сделать быструю конвертацию из MS Word в PDF. А дальше — отправку документов на наш сервер печатной продукции, откуда документы забирает в печать типография.

Инструкция по работе с внезапными находками


Мы так и не сумели отказаться от MS Word, но в процессе поисков замены мы внезапно нашли нечто большее. Confluence объединил разработчиков разных отделов, сформировал базу знаний компании и стал хранилищем всех документов компании, независимо от их формата.

У нас в компании есть принцип: в любой непонятной ситуации принимай решения системно. Мы считаем, что решение, которое опирается на модель — лучше, чем то, что основывается на мнении экспертов или интуиции.

В случае с Confluence нам пригодилась модель Эрика Риса из «The Lean Startup». В продуктовой разработке она помогает делать pivot, менять направление развития продукта. А в задаче поиска замены MS Word — примерять новый инструмент шире, находить смежную пользу.

Желаем коллегам техническим писателям полезных моделей!

Средняя зарплата в IT

110 450 ₽/мес.
Средняя зарплата по всем IT-специализациям на основании 7 043 анкет, за 2-ое пол. 2020 года Узнать свою зарплату
AdBlock похитил этот баннер, но баннеры не зубы — отрастут

Подробнее
Реклама

Комментарии 30

    0
    Первые два инструмента не подошли по одной и той же причине: нам нужны были навыки программирования

    Во-первых, вроде и не нужны, а во-вторых, отсутствие навыков это не повод использовать какие-то странные решения, а повод найти человека с навыками или научится.
      0
      Согласна, учиться нужно, находить нужных людей тоже. Мы не стали этого делать, т.к. в нашем отделе нет такого объёма задач для технических писателей с навыками программирования.
        –1
        А почему вы решили что нужны навыки программирования?
      –2
      Интересно, что фермеры на десятилетия раньше смогли переучиться на инженеров (и не только) чтобы иметь полный контроль над своими инструментами.

      А большая часть профессий в ИТ (собственно все кроме программистов и админов) все еще думает что они лучше справятся со своими обязанностями не умея программировать. Естественно речь про большинство, исключения есть везде.
        0
        Я к сожалению ни разу не пользовался системами для работы с документацией, но имею приятный опыт написания ЕСКД/ЕСПД документации в формате PDF.

        Связка LaTex с git хорошо покрывает задачи совместного редактирования, а одна хорошо написанная преамбула может гарантировать единый воспроизводимый стиль документа.

        Тут конечно есть порог входа, плюс не всегда потребители документации хотят использовать что-то кроме docx формата.
          0
          Да, в нашем случае потребители ЕСКД документов хотят работать исключительно с docx.
            0
            Странно, что заказчик требуют DOCX. Просто на сколько я знаю те кто требует по ЕСКД обычно госорганы. А гос органы должны требовать документы в соответствии с национальными стандартами, а в соответствии со стандартами принят только ODF.
            0

            Вот уж точно, latex здесь лучше всего использовать, тем более есть пакет eskdx.
            Docx, заказчик собирается редактировать эти документы? Тогда с вероятностью 100% документ поплывет. Хотя я сдавал заказчику docx полностью сделанный из картинок из pdf.

            0
            При каждой новой правке свёрстанного в MS Word документа примерно в половине случаев «съезжают» скриншоты, «плывут» таблицы с иконками, а при печати документа и вовсе внезапно появляются невидимые пустые страницы.

            Вообще, так быть не должно. Word при корректной вёрстке выдает достаточно стабильный (стабильно хороший :-) результат на сложных документах. Возможно, вам надо не забывать добавлять разрывы между разделами документов, либо неправильно настроены параметры вставки изображений/таблиц.
              0
              Зачастую недостатки вёрстки выявляются после конвертации docx в pdf, при этом документ docx выглядит хорошо. На «отлавливание» причин уходит иногда достаточно много времени.
                +2
                Не конвертируйте в pdf через «сохранить как», конвертируйте через виртуальный pdf-принтер. В этом случае оно будет выглядеть так, как и в docx.
                  0
                  Спасибо, обязательно попробуем!
                0
                Вообще, так быть не должно. Word при корректной вёрстке выдает достаточно стабильный (стабильно хороший

                По ЕСКД? Чтобы отступы и толщины линий — в мм, некратно долям дюйма? Я его в этом плане так и не победил. Приходится все размеры «прибивать гвоздями» (думаешь — пропади оно пропадом, уже бы в postscript написал), а потом одно неловкое движение мышки сбивает всё обратно на 2,54 и тому подобное.
                  0
                  Я правда, не понимаю, в чем у вас проблема. В Word есть в параметрах переключатель единиц измерения по умолчанию, хотите — дюймы, хотите — сантиметры/миллиметры, хотите типографские пункты. При этом если будут выбраны, например, сантиметры, все отступы будут исключительно в сантиметрах, и никак не будут сбиваться на доли дюйма. Единственное, размеры шрифта и толщины линий задаются всегда в типографских пунктах, а не в дюймах/миллиметрах. Но тут ничего хитрого, 1 мм примерно равен 2.8pt, для корректной вёрстки этого знания достаточно.
                    0
                    Единицы измерения-то переключаются, но, например, граница таблицы при перетаскивании мышкой «прилипает» к позициям дюймовой сетки.
                    Если это не так, то подскажите, с какой версии всё стало хорошо.
                      0
                      Если не ошибаюсь, с Word 6.0, пункт «Размер сетки» в меню ;)
                        0
                        Чёрт возьми, никогда не чувствовал себя настолько ламером… Скорблю о тысячах потерянных часов…
                      0
                      Это не решает вы всех проблем с плывущим форматированием. Я не делаю сложных документов, но даже в простых договорах о паре десятков пунктов в двухколоночной таблице на пару страниц Word порой (хотя и редко) ведёт себя неадекватно. В более сложных документах частота глюков, конечно, будет повышаться.
                  0
                  При каждой новой правке свёрстанного в MS Word документа примерно в половине случаев «съезжают» скриншоты, «плывут» таблицы с иконками, а при печати документа и вовсе внезапно появляются невидимые пустые страницы.


                  Это звучит как «Мы не хотели учиться работать в Word, и вместо этого начали учиться работать в Confluence». Инструмент, несомненно хороший, и радостно за вас, что в итоге получилось сделать некую базу знаний. Но проблемы с Word, так понимаю, остались. Может, посмотреть теперь в сторону обучения работы с ним?
                    0
                    Проблем с MS Word и экспортом в PDF больше нет, так как теперь мы создаём в нём только ЕСКД документы и используем docx — эти документы не нуждаются в экспорте в PDF. Пользовательская документация в свободной форме (не ЕСКД) создается в Confluence и экспортируется в PDF плагином с сохранением вёрстки.
                      0
                      А, понимаю, т.е. у вас были проблемы не при печати на бумаге и просмотре Word после правок, а при конвертации в PDF.
                      Сразу как-то не ясно было, в чем именно проблема.
                    +1
                    Привет коллегам! Тоже больная тема. Сколько Word уже существует, а всё равно кривой. И никуда от него не денешься, потому что сам-то можешь писать в чем угодно, но если надо заказчикам отдавать на согласование — делать нечего.

                    Когда нужно отдать финальный документ без возможности правки — пишу в LaTeX. Конечно, в начале нужно нормально так посидеть поковыряться, постучаться головой об стол из-за очень «понятных» ошибок компиляции, но потом привыкаешь и работать становится даже удобно. Никаких проблем с разметкой, содержанием, со слетевшей нумерацией и форматированием. Насколько знаю, *.tex формат через pandoc можно конвертировать в *.docx (либо в промежуточный, а потом в *.docx).
                      0

                      С pandoc у меня так и не получилось сделать нумерацию всех элементов которые есть в latex. Буду признателен если у вас есть какой-нибудь рецепт для этого.

                        0
                        Да. Я тоже двигался от Латеха, но пришел к org-mode.
                        Вендорлокнутый формат емакса, но благодаря открытости хорошая интероперабельность. Хотя, конечно, не хватает опубликованного стандарта.
                        Пандок умеет напрямую конвертировать в латех. Там можно наложить оформление eskdx и вывести в pdf.
                        Самое приятное — ворд по сути и не понадобится. Org-mode отлично читается в любом текстовом редакторе. Все-таки, документы нужны для совместного редактирования. Отправить org-mode можно любому рецензенту. Он может внести правки и вернуть документ. Выявить правки легко с помощью git. В моем случае — gitea.
                        А редактировать в емаксе его — одно удовольствие: тут тебе и сворачиваение глав, и автоматичиеское форматирование таблиц и вставка ссылок.

                        Если орг-мод не подходит, то следующий кандидат — Asciidoc. К сожалению, тулинг у него практически отсутствует. Я редактирую в VSCode. Просматриваю в браузере.
                        Конвертация в .tex средствами pandoc вроде хорошая, но я не пробовал.
                          +1
                          Плюсую LaTeX. И в docx, и в pdf и вообще во всё.
                          0
                          Посмотрите по теме DocOps — много интересного для вашего случая можно найти.
                            0
                            Концепция единого источника, несомненно, очень помогает повышению производительности совместной работы. Я сам постоянно в поиске идеального инструмента для создания и поддержания проектной документации.
                            Конечно, самое популярный инструмент — это Конфлюенс. Он не идеален.
                            Разработчики тяготеют к работе с маркдаун + git.
                            Поэтому обратите внимание на gitlab.iaaras.ru/iaaras/gostdown
                            Вполне возможно, что для ваших коллег будет трудновато освоить разметку и SourceTree, но в конечном итоге, это того стоит.
                              0
                              Спасибо, обязательно посмотрим!
                              0
                              Из серии примеры борьбы с MS Word.
                              В ИПА РАН создали инструмент написания документации в Markdown с последующей генерации их в docx и pdf gitlab.iaaras.ru/iaaras/gostdown

                            Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

                            Самое читаемое