MS Word регулярно подкидывает нам «сюрпризы»: «съехавшие» скриншоты, «плывущие» таблицы, пустые страницы при печати. Эта статья о том, как мы искали замену MS Word, (спойлер — не нашли), а нашли возможность глобально улучшить наш процесс работы с документацией.
В 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, с какими проблемами столкнулись и как смогли их решить.
Мы почитали статьи на тему существующих инструментов по разработке документации, пообщались с коллегами из других компаний. Наиболее подходящими нам показались следующие инструменты:
Первые два инструмента не подошли по одной и той же причине: нам нужны были навыки программирования, которых у нас не было, а для создания нового шаблона документа пришлось бы звать на помощь программиста. Переход на работу с ними по нашим представлениям занял бы около полугода, возможно больше. Из-за перечисленных минусов мы решили отказаться от полноценного тестирования этих инструментов.
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 в качестве инструмента, который одновременно бы решал три задачи:
Наши ожидания от функционала Confluence оправдались не полностью, но после завершения тестирования сформировалось в целом положительное отношение к этому инструменту. Ниже мы сформулировали его основные плюсы для нашего отдела:
Для внедрения Confluence мы выделили из отдела технических писателей двух специалистов, которые изучали и тестировали возможности инструмента.
Для непрерывной технической поддержки отдел системных администраторов выделил нам одного специалиста. Он оперативно реагировал на технические проблемы и помогал разобраться с базовыми настройками нового инструмента.
В то же самое время мы создали в отделе технических писателей рабочую группу, задачей которой было планирование структуры хранения данных. Вся структура нашего сервера была разделена на категории, соответствующие типам проектов компании. Категории в свою очередь делились на пространства по продуктам компании. Мы также выделили отдельную категорию для внутренней базы знаний.
Когда ответственные за тестирование системы достаточно глубоко изучили работу в Confluence, начался этап взаимного обучения коллег. На передачу знаний всему отделу понадобилось около месяца.
Внедрение Confluence в целом проходило достаточно гладко, но были и проблемы.
«Раньше я делал это в MS Word за пару секунд. Как сделать то же самое в Confluence?» — такой вопрос мы задавали себе каждый день в течение всего времени тестирования.
Так, было совсем неочевидно, как выровнять содержимое таблицы по вертикали или назначить иконке размер меньше 16 px.
Действительно, базовый набор функций форматирования страниц в WYSIWYG-редакторе Confluence в значительной степени проигрывает MS Word, однако функционал можно значительно расширить, если зайти в режим редактирования исходного кода и работать напрямую с HTML-кодом.
Мы читали статьи, смотрели обучающие видеоролики по HTML-вёрстке и обменивались найденными решениями. Мы создали отдельную страницу в Confluence, куда разместили полезную информацию по работе с этим инструментом.
После первого обновления основного плагина Scroll PDF Exporter слетело 80% макросов и поехала структура страниц в Confluence. Позже выяснилось, что случилось так из-за нового функционала плагина. Всем отделом мы восстанавливали структуру документов несколько дней. После этого мы составили план обновления на будущее, которого придерживаемся до сих пор:
Когда в Confluence наконец закипела бурная деятельность технических писателей и разработчиков, администратору посыпались звонки от пользователей сервиса. Они просили избавить их от массовой атаки почтовыми уведомлениями о действиях других пользователей.
По умолчанию пользователю нужно было всего лишь раз зайти на какую-нибудь страницу, после чего он автоматически добавлялся системой в список наблюдателей и получал уведомления при каждом изменении этой страницы.
Вдобавок к этому Confluence любезно делал еженедельную рассылку пользователям с перечислением самых популярных страниц Confluence. К счастью, эта проблема уже широко была освещена в интернете. Решение — отключить соответствующие уведомления в настройках системы:
Теперь пользователи получают уведомления, только если их имя упомянуто в комментариях к статье.
Для тестирования Confluence мы развернули Windows-сервер. На первоначальных этапах сервер часто «падал». Часть проблемы оказалась в недостаточном объёме оперативной памяти на сервере (рекомендованный объём 11-12 ГБ). Оставшиеся проблемы ушли, когда мы включили рекомендованные в таких случаях настройки системы.
Сейчас сервер работает достаточно стабильно — нарушение в работе случаются примерно 1 раз в 2 месяца. В случае сбоя достаточно перезагрузки для его восстановления.
На сегодняшний день в Confluence совместно работают технические писатели, программисты, электронщики, QA.
Мы планировали полностью отказаться от MS Word, разрабатывать документы исключительно в Confluence и преобразовывать их в DOCX и PDF. В реальности оказалось, что можно обойтись без длительного процесса переноса всей существующей документации в новый формат и последующей настройки шаблонов в Scroll PDF/Word Exporter. По нашим оценкам нам потребовалось бы на это около полугода. Гораздо проще оказалось перенести все разработанные документы в формате MS Word в Confluence и поддерживать их там же.
Мы решили не ждать от Confluence чудесного форматирования по всем требованиям ЕСКД и просто разделили все пользовательские документы условно на документы для «госзаказчика» и документы для «не госзаказчика».
Первые мы создаём в формате DOCX, храним и актуализируем в Confluence. Вторые разрабатываем прямо в Confluence, экспортируем в PDF при необходимости.
Благодаря встроенным макросам мы используем технологию единого источника в пользовательской документации — теперь не приходится вручную менять один параметр в нескольких версиях документов.
Удобный WYSIWYG-редактор позволяет легче вносить изменения в готовый документ — скриншоты, иконки и графические элементы остаются на месте.
Функция совместного редактирования статей позволяет совместно работать над документом. Можно поделиться документом с техническим экспертом прямо в Confluence и обсуждать его замечания в реальном времени, а не перекидываться бесконечно документом по почте.
Для работы вне офиса не нужно настраивать удалённый доступ. Чтобы иметь возможность поработать из дома, нужен только интернет.
Confluence предлагает пользователю уже привычный всем интерфейс веб-страницы с возможностью настроить cross-ссылки и открыть в браузере для работы сразу несколько вкладок.
Теперь мы храним все документы, графические элементы, фото устройств, а также ведем базу знаний по продуктам компании в одном месте. Нет нужды думать, где могут лежать исходники рисунков или самая свежая версия документов.
В настоящий момент мы настраиваем процесс согласования страниц Confluence с помощью плагина Comala Workflow. Однако, этот плагин не работает с вложениями MS Word. Такие документы мы согласовываем с помощью комментариев к версиям. Сейчас мы рассматриваем варианты настройки автоматического согласования вложений DOCX. Хочется, чтобы процесс согласования и утверждения можно было одновременно использовать как со страницами Confluence, так и с вложениями формата DOCX.
Когда настроим автоматическое согласование вложений, попробуем сделать быструю конвертацию из MS Word в PDF. А дальше — отправку документов на наш сервер печатной продукции, откуда документы забирает в печать типография.
Мы так и не сумели отказаться от MS Word, но в процессе поисков замены мы внезапно нашли нечто большее. Confluence объединил разработчиков разных отделов, сформировал базу знаний компании и стал хранилищем всех документов компании, независимо от их формата.
У нас в компании есть принцип: в любой непонятной ситуации принимай решения системно. Мы считаем, что решение, которое опирается на модель — лучше, чем то, что основывается на мнении экспертов или интуиции.
В случае с Confluence нам пригодилась модель Эрика Риса из «The Lean Startup». В продуктовой разработке она помогает делать pivot, менять направление развития продукта. А в задаче поиска замены MS Word — примерять новый инструмент шире, находить смежную пользу.
Желаем коллегам техническим писателям полезных моделей!
В 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 в качестве инструмента, который одновременно бы решал три задачи:
- Создание базы знаний.
- Разработка, хранение и актуализация документации, разрабатываемой не по ГОСТу.
- Хранение и актуализация документации, разрабатываемой по ГОСТу.
Потенциал Confluence
Наши ожидания от функционала Confluence оправдались не полностью, но после завершения тестирования сформировалось в целом положительное отношение к этому инструменту. Ниже мы сформулировали его основные плюсы для нашего отдела:
- Настройка и поддержка инструмента своими силами.
- Простота освоения.
- Возможность организовать базу знаний о продуктах компании и хранить всю свёрстанную документацию в DOCX и PDF в одном месте.
- Поддержка версионности документов.
- Возможность использования технологии единого источника.
- Возможность совместной работы разработчиков и технических писателей над документами.
- Хранение рабочих документов и информации в одном месте.
- Возможность разрабатывать документы в любое время из любой точки мира.
Внедрение
Для внедрения Confluence мы выделили из отдела технических писателей двух специалистов, которые изучали и тестировали возможности инструмента.
Для непрерывной технической поддержки отдел системных администраторов выделил нам одного специалиста. Он оперативно реагировал на технические проблемы и помогал разобраться с базовыми настройками нового инструмента.
В то же самое время мы создали в отделе технических писателей рабочую группу, задачей которой было планирование структуры хранения данных. Вся структура нашего сервера была разделена на категории, соответствующие типам проектов компании. Категории в свою очередь делились на пространства по продуктам компании. Мы также выделили отдельную категорию для внутренней базы знаний.
Когда ответственные за тестирование системы достаточно глубоко изучили работу в Confluence, начался этап взаимного обучения коллег. На передачу знаний всему отделу понадобилось около месяца.
Технические проблемы
Внедрение Confluence в целом проходило достаточно гладко, но были и проблемы.
Вёрстка и предпечатная подготовка документов
«Раньше я делал это в MS Word за пару секунд. Как сделать то же самое в Confluence?» — такой вопрос мы задавали себе каждый день в течение всего времени тестирования.
Так, было совсем неочевидно, как выровнять содержимое таблицы по вертикали или назначить иконке размер меньше 16 px.
Действительно, базовый набор функций форматирования страниц в WYSIWYG-редакторе Confluence в значительной степени проигрывает MS Word, однако функционал можно значительно расширить, если зайти в режим редактирования исходного кода и работать напрямую с HTML-кодом.
Мы читали статьи, смотрели обучающие видеоролики по HTML-вёрстке и обменивались найденными решениями. Мы создали отдельную страницу в Confluence, куда разместили полезную информацию по работе с этим инструментом.
Обновление версии Confluence и плагинов
После первого обновления основного плагина Scroll PDF Exporter слетело 80% макросов и поехала структура страниц в Confluence. Позже выяснилось, что случилось так из-за нового функционала плагина. Всем отделом мы восстанавливали структуру документов несколько дней. После этого мы составили план обновления на будущее, которого придерживаемся до сих пор:
- Проводите обновление в пятницу, когда выполнен основной пласт работ за неделю, чтобы иметь возможность устранить возможные проблемы на выходных.
- Сделайте рассылку всем пользователям системы, чтобы сообщить им о времени запланированного обновления.
- Перед обновлением выполните резервное копирование сервера.
- Обновите версию Confluence.
- Протестируйте сервер, убедитесь, что вся информация на месте, работают ссылки на внешние и внутренние ресурсы.
- При необходимости обновить плагины снова выполните резервное копирование сервера.
- Проводите обновление плагинов по принципу один плагин за раз.
- Тестируйте работу плагина сразу после обновления.
Массовые уведомления
Когда в Confluence наконец закипела бурная деятельность технических писателей и разработчиков, администратору посыпались звонки от пользователей сервиса. Они просили избавить их от массовой атаки почтовыми уведомлениями о действиях других пользователей.
По умолчанию пользователю нужно было всего лишь раз зайти на какую-нибудь страницу, после чего он автоматически добавлялся системой в список наблюдателей и получал уведомления при каждом изменении этой страницы.
Вдобавок к этому Confluence любезно делал еженедельную рассылку пользователям с перечислением самых популярных страниц Confluence. К счастью, эта проблема уже широко была освещена в интернете. Решение — отключить соответствующие уведомления в настройках системы:
Теперь пользователи получают уведомления, только если их имя упомянуто в комментариях к статье.
Стабильность сервера
Для тестирования 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-редактор позволяет легче вносить изменения в готовый документ — скриншоты, иконки и графические элементы остаются на месте.
Функция совместного редактирования статей позволяет совместно работать над документом. Можно поделиться документом с техническим экспертом прямо в Confluence и обсуждать его замечания в реальном времени, а не перекидываться бесконечно документом по почте.
Для работы вне офиса не нужно настраивать удалённый доступ. Чтобы иметь возможность поработать из дома, нужен только интернет.
Confluence предлагает пользователю уже привычный всем интерфейс веб-страницы с возможностью настроить cross-ссылки и открыть в браузере для работы сразу несколько вкладок.
Теперь мы храним все документы, графические элементы, фото устройств, а также ведем базу знаний по продуктам компании в одном месте. Нет нужды думать, где могут лежать исходники рисунков или самая свежая версия документов.
Что ещё хочется сделать
В настоящий момент мы настраиваем процесс согласования страниц Confluence с помощью плагина Comala Workflow. Однако, этот плагин не работает с вложениями MS Word. Такие документы мы согласовываем с помощью комментариев к версиям. Сейчас мы рассматриваем варианты настройки автоматического согласования вложений DOCX. Хочется, чтобы процесс согласования и утверждения можно было одновременно использовать как со страницами Confluence, так и с вложениями формата DOCX.
Когда настроим автоматическое согласование вложений, попробуем сделать быструю конвертацию из MS Word в PDF. А дальше — отправку документов на наш сервер печатной продукции, откуда документы забирает в печать типография.
Инструкция по работе с внезапными находками
Мы так и не сумели отказаться от MS Word, но в процессе поисков замены мы внезапно нашли нечто большее. Confluence объединил разработчиков разных отделов, сформировал базу знаний компании и стал хранилищем всех документов компании, независимо от их формата.
У нас в компании есть принцип: в любой непонятной ситуации принимай решения системно. Мы считаем, что решение, которое опирается на модель — лучше, чем то, что основывается на мнении экспертов или интуиции.
В случае с Confluence нам пригодилась модель Эрика Риса из «The Lean Startup». В продуктовой разработке она помогает делать pivot, менять направление развития продукта. А в задаче поиска замены MS Word — примерять новый инструмент шире, находить смежную пользу.
Желаем коллегам техническим писателям полезных моделей!
