Эволюция пользовательской документации 1С в производственной компании

Общая информация

Группа компаний «Доброфлот» – это крупная рыбодобывающая компания со своим флотом и производством консервов. В компании работает более 3500 сотрудников, из которых около тысячи – это активные пользователи бизнес-приложений и информационных технологий. Эти пользователи регулярно обращаются в службу технической поддержки за консультациями.

В компании порядка 15 конфигурации 1С. Часть конфигураций (порядка 5 штук) написаны собственными силами компании. У нас есть направление разработки, которое состоит из 5 разработчиков и одного тимлида (данные на осень 2018 года, сейчас направление разработки расширилось). Любой пользователь может поставить задачу на разработку или изменение функционала. Разработчики в течение недели отрабатывают эти задачи, и каждый понедельник утром изменения вносятся в продакшн. То есть каждый понедельник мы получаем обновленный функционал и массу пользовательских обращений. Эти обращения мы закрываем двумя консультантами 1С и информацией из пользовательской документации, которую готовит технический писатель.

Что такое пользовательская документация?

Я сформулировал такое определение – «Это печатные или электронные руководства пользователя и справочный текст, описывающий методы использования информационных систем и бизнес-приложений».

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

Зачем и кому нужна пользовательская документация?

Подобие пользовательской документации появилось в 20-40 годы прошлого века в эпоху индустриализации. Появлялись новые системы, автоматизированные станки и швейные машинки. Мало кто умел ими пользоваться, кроме тех инженеров, которые их создали. Нужно было как-то передавать информацию, но старый способ – от мастера к подмастерью уже не работал, потому что объемы информации были огромными. На помощь пришли инструкции и описания новых систем.

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

Отсюда хочется сделать первый вывод (мы сегодня будем делать выводы, я их назвал «выводы пользовательской документации»), который гласит – «Пишите пользовательскую документацию».

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

Кто готовит пользовательскую документацию?

В идеале документацию готовит специальный человек – технический писатель. Кто такой технический писатель?

Это интересная, востребованная и редкая профессия. Я сформулировал такое определение  – «Это роль сотрудника, в должностные обязанности которого входит разработка и актуализация пользовательской документации».

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

Отсюда хочется сделать следующий вывод – «Пользовательскую документацию пишет сотрудник, который умеет и любит писать». Не заставляйте своего разработчика писать документацию, потому что в итоге вы получите плохую документацию, злых пользователей, потому что документация будет малопонятной, и злого разработчика, потому что он не хочет этим заниматься.

Мой опыт знакомства с пользовательской документацией

С пользовательской документацией я познакомился, когда пришел в группу компаний «Доброфлот». Коллеги показали мне корпоративный портал и раздел с документацией. Сказали, что я должен буду писать документацию в MS Word и конвертировать ее в pdf файлы и публиковать эти файлы на портале. «Круто! У них есть документация для пользователей!», подумал тогда я, но на практике все оказалось иначе. Я сразу столкнулся с тем, что некоторые пользователи, вообще не знали, что на портале есть документация. Однажды мне позвонил пользователь и говорит: «Я не могу заполнить требование-накладную, я не понимаю что мне делать». Я предлагаю ему скачать документацию, где описано как это сделать. На что пользователь отвечает: «А что у нас есть какие-то инструкции по 1С?». И это спрашивал пользователь, который работал в компании больше года. Что-то работало не так.

Потом оказалось, что о пользовательской документации знают лишь единицы, большинство сотрудников о ней не знали. Тогда я понял, что нужно рекламировать документацию. Я начал точечно рекламировал документацию пользователям – давать им ссылки на документацию во время консультаций. Я был тогда единственным консультантом и иногда исполнял обязанности технического писателя. Но было понятно, что в большой компании такой рекламой документацию пользователям не продать. Мне хотелось отгружать документацию оптом. Так как нет ничего хуже документации, которую никто не читает. Тогда появилась идея запустить новостную колонку на портале – «Новости бизнес-приложений», где мы начали публиковать мини-инструкции, анонсы на новую документацию и изменения в бизнес-приложениях за последнюю неделю.

Чуть позже мы сделали публикацию новостей еженедельной и начали делать рассылки новостей на корпоративную почту пользователей.

Забавный факт. Если в заголовке новости написать слова «зарплата или аванс», то это будет очень популярная по просмотрам новость.

Новости действительно работают, это показывает аналитика за последнее время с 04.05.2016 по 19.09.2018. Всего за период 04.05.2016-19.09.2018 было опубликовано 498 новостей. Просмотры растут, значит мы делаем все правильно.

Все новости разбиты на разделы, и пользователи подписываются на те разделы, которые им интересны. Если углубиться в просмотры новостей по разделам, то можно увидеть, что на первом месте у нас управленческий учет. Управленческий учет – это такой раздел новостей, где мы пишем об изменениях в 1С:УПП, где у нас автоматизирована большая часть бизнес-процессов. На втором месте – пользовательская документация.

Отсюда мы получаем вывод – «Сообщайте пользователям о наличии пользовательской документации». Если у вас есть документация, то не держите эту информацию в тайне. Поделитесь документацией с пользователи любыми доступными вам способами.

Актуализация пользовательской документации

Теперь наши пользователи знали, что у них есть документация. Но мне снова позвонил пользователь и говорит: «Я не могу создать контрагента, у меня там какая-то ошибка». Я понимаю, что это за ошибка, знаю, что она описана в документации и предлагаю пользователю разобраться самостоятельно. Объясняю, в каком документе описано решение его проблемы. Пользователь соглашается и кладет трубку. Потом снова перезванивает мне и говорит, что он почитал документацию, но там описано то, что не соответствует действительности. Я смотрю документы и вижу, что там описан устаревший функционал, который был актуален пару месяцев назад. Мне становится стыдно: «Заставил пользователя потратить время впустую». И таких случаев становилось все больше. У нас есть документация, все про нее знают, но она старая и не соответствует реальному ходу вещей. Поэтому было решено актуализировать документацию.

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

Откуда, вообще, взялась устаревшая документация и почему она была опубликована на корпоративном портале? Вначале процесс разработки и публикации документации был устроен следующим образом:

1. Пользователь заводил задачу на разработку функционала;

2. Разработчик создавал требуемый функционал;

3. Пользователь параллельно заводил отдельную задачу на подготовку документации;

4. Консультант готовил документацию;

5. Пользователь получал свой функционал и опубликованную документацию на портале.

Шли дни, разработчики исправляли баги, делали рефакторинг кода, функционал менялся, а документация так и лежала на портале без изменений. И таких документов у нас было порядка 70 штук.

Чтобы это побороть был написан регламент, где было указано, что каждый документ имеет свой срок годности и этот срок равен 6 месяцам. То есть каждый 6 месяц мы обязаны провести актуализацию документа, иначе он считается старым и недействительным. Таким образом мы избавились от появления старой документации. И это был первый триггер актуализации. Причем мы автоматизировали это в 1С: Документооборот (далее 1С: ДО), там можно указывать срок действия документа и отправлять автоматические уведомления ответственному о необходимости актуализации документа. Второй триггер актуализации это внесение изменений в функционал. Если технический писатель или консультант видят, что в хранилище описанной конфигурации что-то поменялось и это как-то влияет на результат описанный в документации, то заводится задача на актуализацию документации.

Получаем вывод – «Непрерывно актуализируйте пользовательскую документацию». Потому что если пользователь придет к вам за знаниями и получит неправильные или устаревшие данные, то он больше к вам не вернется.

Главный тезис любой документации

Чтобы вы ни улучшали, всегда в голове держите тезис – «Пользователи не хотят и не любят читать документацию». Это аксиома, но плохо написанную документацию вдвойне никто не любит читать. Если и читать, то читать хорошую документацию. А что же такое хорошая документация?

У каждого свои критерии хорошей пользовательской документации. Я выделил следующие критерии:

1. Документация максимально краткая и лаконичная;

2. Документация однозначная. Если мы описываем элемент как «закладка документа», то значит мы везде пишем, что это «закладка документа», никаких «вкладок документа» или чего-то иного;

3. Документация не содержит ошибок – грамматических, пунктуационных и орфографических;

4. Документация не содержит сленга. Неправильно писать «введите айпишник». Нужно писать «введите IP адрес»;

5. Документация в едином стиле.

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

• использование определенных цветов;

• список стоп-слов;

• единые словесные конструкции;

• правила форматирования и т.д.

Но когда нас стало двое, то каждый раз мне приходилось объяснять коллеге, как можно писать, а как писать нельзя, как обрезать скриншоты и т.д. А потом документацию стало писать три человека. Нам были нужны единые правила. Тогда мы разработали и согласовали свой Style Guide или по-русски – руководство по стилю. В руководство были включены: описания обрезки скриншотов, допустимые шрифты, разрешенные цвета, сокращения, форматирования таблиц и текста, стоп-слова и многое другое. И теперь при подготовке документации все, кто занимается документацией, ориентировались на руководство по стилю. Отойти от правил считается ошибкой.

Отсюда получаем вывод – «Установите единые правила написания пользовательской документации». Если в вашей компании документацию пишет больше одного человека, то согласуйте свой Style Guide. Установите правила и контролируйте их выполнение. Иначе вы получите хаос и разночтение, а пользователи получат плохую документацию.

1С:Документооборот – удобный инструмент для подготовки пользовательской документации

У нас в компании активно используются 1С:ДО. В частности для согласования договоров, приказов и других значимых документов. Мы также используем 1С:ДО для постановки задач на разработку и актуализацию документации, и для хранения документации.

Но самое важное – в 1С:ДО мы можем ставить задачи на ознакомление пользователей с документацией. Если кратко описать текущий процесс разработки и актуализации документации, то получается так:

• Заказчик ставит задачу в 1С:ДО, я ее проверяю и согласовываю.

• Далее задача идет на оценку трудоемкости техническому писателю, он указывает плановый срок выполнения задачи и пишет документацию.

• Дальше идет процесс согласования подготовленной документации.

• Заказчик готовит список пользователей, для которых эта документация предназначена.

• Всем указанным пользователям из списка отправляется задача на ознакомление с документацией.

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

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

Отсюда получаем еще один вывод – «Используйте все доступные средства продвижения пользовательской документации». В борьбе все средства хороши.

Если документацию пишет и проверяет один и тот же человек, то с большой вероятностью в ней могут содержаться грамматические и орфографические ошибки. Чтобы минимизировать эту вероятность, мы добавили в процесс разработки документации в 1С: ДО – согласование корректора. Вначале документ вычитывает сам писатель, потом корректор и только после этого документ идет дальше по процессу.

Кроме грамматических и орфографических ошибок, в документации могут быть неверно описаны бизнес-процессы. Поэтому нам пришлось еще усложнить процесс проверки документации и добавить в процесс в 1С: ДО – согласование методолога. Методологи это хранители знаний регламентов компании. У нас в процессе методологи проверяют корректность описанных бизнес-процессов в документации. Например, технический писатель пишет: «Чтобы указать фактические даты командировки через три рабочих дня зайдите в документ и установите значение в соответствующем поле». А методолог знает, что это нужно сделать через два рабочих дня, вносит замечание в документацию и направляет документацию на доработку. В итоге наша документация стала еще более качественной. Нам уже было совсем не стыдно давать читать пользователям такую документацию. 

Получаем вывод – «Используйте перекрестную вычитку и проверяйте методологию». Делайте так, если хотите чтобы ваша документация была максимально качественной.

Сколько стоит пользовательская документация?

В какой-то момент нам стало интересно, а сколько стоит пользовательская документация? Так как мы используем 1С:ДО, то посчитать стоимость документации относительно просто.

Потому что все участники процесса подготовки документации указывают фактически затраченное время в 1С:ДО. Мы можем взять часовую тарифную ставку участника подготовки документации, фактически потраченное им время, умножить эти показатели, а затем просуммировать цифры по всем участникам и получить стоимость услуги по подготовке пользовательской документации. А когда у нас много документации и есть экспертный опыт, то мы даже можем примерно рассчитать сколько в среднем стоит одна страница документации.

Например, если пользователь просит разработать документ, то я задаю ему вопросы: «А кто будет читать эту документацию? Сколько человек?». Пользователь отвечает: «Ну я, может еще кладовщик, ну не знаю». А я знаю, что никто кроме этого пользователя не будет читать эту документацию, так как это базовый функционал и в поддержку никто ещё не обращался за такими консультациями. Допустим, что стоимость такой документации будет составлять 15 000 каких-нибудь условных единиц и представим, что это очень дорого. Нам будет дешевле точечно проконсультировать пользователя или написать небольшую статью в новостях на портале, чем готовить полноценную документацию, которой никто не будет пользоваться, а стоить это будет очень дорого. Также мы можем посмотреть статистику скачиваний документации на портале. Понять насколько выгодные документы мы пишем и сделать соответствующие выводы: «Нужна ли нам такая документация или мы ее написали зря?».

Мы можем получать экспертную оценку на основании плана и факта из 1С:ДО, то есть заранее определять сколько времени нам потребуется на разработку той или иной документации. Это полезные данные для проектных менеджеров. Практически в любом проекте всегда есть документация. Мы можем использовать экспертную оценку для планирования задач на подготовку документации.

Отсюда получаем следующий вывод – «Измеряйте разработку пользовательской документации».

Формат пользовательской документации

Исторически сложилось, что у нас документация хранится в формате pdf.

Этот формат прижился у нас в компании для любых документов, так как у нас есть суда и склады, и там люди распечатывают документацию. Им удобно скачать документ с портала, распечатать его и положить к себе на стол, а потом использовать при необходимости.

Но в пользовательской документации в формате pdf есть минусы:

1. Документы огромные и тяжелые. Если нужно внести изменение в документацию, то вначале нужно внести изменение в файл doc в MS Word, потом конвертировать файл в pdf и только потом переопубликовать его на корпоративном портале. Потом документация скачивается на локальные машины и если пользователь пропустит новость об обновлении документации, то он будет пользоваться старой версией. Обычно документация в pdf это огромная книжка, ее нужно скачать и полистать для того чтобы найти нужную информацию. Этот процесс занимает большое количество времени.

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

3. Документы не интерактивные. Мы не можем добавить в документацию анимацию или видео. А ведь иногда быстрее показать какую-то анимацию пользователю, чем писать документ на 15 страниц.

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

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

То же самое можно сказать и о wiki-деревьях. Есть много удобных решений для организации контентных деревьев из коробки.

Плюсы деревьев html и wiki:

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

• Во-вторых, они измеримы. Мы можем подключить к контентному дереву Яндекс.Метрику, Google Analytics или еще какие-нибудь инструменты для аналитики. И, например, понимать, где пользователь больше всего задерживается, а где он вообще не бывает.

• В-третьих, они интерактивны. Поэтому мы можем добавлять туда анимацию, видео и другие медиафайлы.

Сейчас мы занимаемся переносом всей документации из pdf формата в контентное дерево. В дальнейшем мы хотим, чтобы дерево документации на корпоративном портале соответствовало встроенной справке в конфигурациях 1С. Для этого мы пишем html документацию в 1С: СППР.

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

Выводы

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

На данный момент мы выращиваем у себя контентное дерево и приходим к контентной архитектуре. В дальнейшем мы хотим освоить технологию DITA (Darwin Information Typing Architecture). Эта технология была придумана в IBM и основана на xml. DITA охватывает весь цикл разработки, выпуска и публикации документации. Одним из плюсов этой технологии является то, что она позволяет переиспользовать контент из единого источника и мы можем повторно использовать части одной документации в других документах. Подробнее об этой технологии можно узнать в соответствующих статьях и докладах.

Сейчас мы уходим от pdf и doc формата, переходим в контентное дерево, а далее планируем переход на xml. Это наша стратегия на ближайшие пару-тройку лет, но, возможно, со временем она изменится.

Отсюда хочется сделать последний вывод – «Непрерывно улучшайте пользовательскую документацию». Эволюция пользовательской документации – это непрерывный процесс и этой эволюцией могут управлять только люди, которые в этом заинтересованы.

Для управления эволюцией пользовательской документации рекомендуется применять и адаптировать описанный опыт, который кратко сформирован в практических выводах:

1. «Пишите пользовательскую документацию».

2. «Пользовательскую документацию пишет сотрудник, который умеет и любит писать».

3. «Сообщайте пользователям о наличии пользовательской документации».

4. «Непрерывно актуализируйте пользовательскую документацию».

5. «Установите единые правила написания пользовательской документации».

6. «Используйте все доступные средства продвижения пользовательской документации».

7. «Используйте перекрестную вычитку и проверяйте методологию».

8. «Измеряйте разработку пользовательской документации».

9. «Непрерывно улучшайте пользовательскую документацию».

Данная статья написана по итогам доклада, прочитанного на конференции INFOSTART EVENT 2018 EDUCATION.