Всем привет.

Меня зовут Саша, я технический писатель компании CSI, но, ко всему прочему, занимаюсь различными проектами в команде разработки. Давно меня не было со статьями на Хабре — накопилось, чем поделиться. Считайте, что сегодня вы зашли ко мне на работу, плюхнулись в пуфики и я вот просто так рассказываю вам про наш портальчик. Берите кофе, подушки в виде котиков и читайте.

Как и полагается, наша команда пишет техническую документацию по ИТ-продуктам компании. Всю публичную документацию мы ведем на портале поддержки, который развернут в инстансе Atlassian Confluence Cloud. Об этом и поговорим: как мы к этому шли, как работали над структурой и принципами подготовки материалов, в чем профит такого подхода. 

В начале было слово…

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

Основные задачи порталов поддержки софта для ритейлера:

• сокращать время поддержки ритейлера или партнера на решения по установке и настройке функциональности;

• найти нужный ответ по той или иной фиче и пример её работы, желательно с последовательностью шагов;

• поддержке нужны всякие волшебные скрипты с инструментами и статьями How to fix, чтобы быстро решить все вопросы по заявке;

• скачать дистрибутивы и обновления, и поподробнее узнать о них.

Желательно, чтобы всё это приходило пользователю по конкретным каналам и он сам шел в нужный раздел. 

Еще 10 лет назад у нас был внутренний корпоративный портал, который на тот период времени закрывал наши потребности в продуктах и предоставлении поддержки. Он вертелся у нас на dokuWiki в нашем дата-центре. На нем были инженерные инструкции со всякими файлами. В этом и был весь прикол. Что была какая-то хаотичная структура, НО людям достаточно было на странице портала просто разместить скоуп инструкций и файликов, а также сделать какую-нибудь страничку с виджетами. Да-да, на тот момент это был норм вариант.

Собственно, чего мучиться: сделал страничку, бросил файлики PDF и WORD, и дело в шляпе. Без привязки к релизу и остальному.

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

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

Мы стали искать решение, которое нас бы выручило, и остановились на Google Sites. Собрались с командой инженеров, структурировали портал и запилили его уже в публичное пространство.

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

Пайплайн разработки

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

Плюс ко всему, мы начали замечать, что текущая функциональность Google Site и dokuWiki нас начала стеснять. Как минимум, замедляя процесс создания документации. 

Ну и главный для нас вопрос был в том, что мы были отделены от разработки. К тому времени наши разработчики уже использовали Atlassian Jira Cloud, поэтому вроде как тут сразу напрашивался вариант с Confluence, также в облачном инстансе. Тут тебе и привязка к Jira, и все ништяки. Но нам нужно было создать процесс, который будет учитывать не только встроенный пайплайн документирования вместе с релизом, но и оптимальный публичный портал поддержки, который учитывает запросы как инженеров поддержки, так и просто ИТ-пользователей, которые хотят найти там что-то интересное по нашим продуктам.

Тяжелый процесс

Начали трудоемкий процесс внедрения Confluence. Выделили типы команд внутри компании:

• сервисные;

• продуктовые;

• разработка;

• административные.

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

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

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

Первый взгляд

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

Мы обратили внимание, что структура в какой-то мере учитывает потребности сервисной поддержки, но совсем выбита из релиза продукта.

Поэтому первой задачей было не просто перенести всё в Confluence из Google Sites (к слову, миграция была отдельная песня со своими костылями), но главное, наложить это на оптимальный процесс.

В итоге мы пришли к варианту, когда наши продукты выходят во внутреннем релизе, уже после код-фриза и тестирования. Затем команда технических писателей приступает к документированию, причем статьи пишутся и публикуются сразу перед заливкой дистрибутива. Когда документирование окончено, специально созданный job в Jenkins, используя REST API Confluence, сам создает ветки страницы для скачивания с версией и сам её заливает. 

Нагрузили

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

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

Вишенка

Результатом всего это стало то, что статьи, которые мы пишем по релизу, публикуются в Confluence вместе с версией.

Мы ушли от старой структуры и сделали стартовую точку от конкретного продукта.

Что-то забыли?

Остановлюсь ещё на том, как мы пишем статьи для портала. Основная задача любого портала поддержки — сокращать затраты на сервис, а наше ПО достаточно объемное по функциональности. В какой-то момент мы, анализируя контент, поняли, что восприятие инструкций (особенно по включению функциональности) может быть разным у людей не то, что из разных городов, а за соседним столом. Это создавало кучу проблем нашей поддержке. 

Поэтому мы приняли решение всегда создавать подробные пошаговые инструкции. Тут можно сказать, что это перебор, мол, контент становится объемным, но нужно понимать специфику и трудозатраты поддержки. Посидев месяц в ХелпДеске, мы увидели, что по факту все обращения содержат в себе вопрос, на который сотрудник поддержки каждый раз отвечает конкретным набором шагов. 

Рассмотрим две инструкции. Одну техническую, другую функциональную.

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

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

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

Конечно, мы на этом не останавливаемся и продолжаем по возможности автоматизировать работу портала и нашу с ним. 

Почему «лучший»?!

Внимательный читатель, увидев амбициозный заголовок, подумает «Автор, конечно, высокого мнения о себе!», что будет вполне логично. Но вот почему мы в этом уверены: 

1. Когда мы перешли на Confluence, мы стали практиковать исправление документации по фидбеку от наших партнеров и клиентов. В какой-то момент нам и этого показалось мало, ведь простой пользователь, как никто другой, видит документацию совершенно с другой стороны. Поэтому мы внедрили на сайте специальную форму, в которую может написать любой, даже анонимно, с просьбой или вопросом об ошибке в документации. Именно наши пользователи с такими отзывами помогают нам совершенствовать портал. Данные из этой формы автоматически попадают на доску Jira.

2. Сейчас, как и говорилось ранее, у нас налажен четкий пайплайн выпуска документации. Тут опять же у читателя возникнет вопрос «А что, вот ты реально всё это один делаешь и твоя команда?». Конечно, нет. Когда прошло годиков так 3-4, то ребята-оунеры из разработки, увидев, что с помощью качественной документации можно не только донести клиенту или партнеру свой продукт, но и установить контакт, сами присоединились к нашему комьюнити. Да-да. Например, страницы таких продуктов, как станция самообслуживания CSI K, сервис для работы с маркированной продукцией Set Mark на портале ведут уже сами продакт-оунеры, а моя команда только выступает как ревьюер. Ребята сами уже подтянулись к нашему стилю, поэтому иногда даже ревьюить за ними нечего. Такая коллаборация технических писателей и продакт-оунеров дает потрясающий профит доставки продукта.

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

Кто читает 

Отдельно стоит сказать об аудитории портала. Вы спросите: «а вы вообще как-то видите свою аудиторию? Как-то измеряете?»

Конечно. В Confluence Cloud мы сразу подключили Google Analytics. Я не буду тут приводить всякие няшные диаграммки и сравнения, для начала просто подкину вам свежий скриншотик за период с 01.01.2022. В среднем к нам приходит около 400 сеансов в день. Не знаю, много это или мало, но, если сравнивать с показателями 4-5 летней давности, то прирост хороший при 20 сеансах в прошлом.

Но и это еще не всё. С помощью Google Analytics и одного лайфхака, который я смог сделать, мы даже смогли вытащить поисковые фразы пользователей! А это очень ценный материал. Мне многие, у кого продукты Atlassian, говорили, что сделать это невозможно, но, как оказалось, есть выход, о чем подробно я написал How to see users search phrases in Confluence Cloud in Google Analytics and parse it?.

Благодаря такому способу (костыльному, но всё же), нам удалось сделать отчет и сфокусировать силы именно на том контенте, который нужен пользователям, на том, что они чаще ищут. 

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

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

Сначала сосредоточились на том, что полностью обновили раздел с интеграцией, затем пошли последовательно улучшать остальное.

Контент в массы

И, конечно же, мы подумали о том, как наш контент пропиарить. Да-да, кому-то кажется, что продумать процессы, сделать архитектуру портала, внедрить, писать грамотные статьи — это уже всё. Нет. Надо раскручивать контент. Мы пошли уже по всем известным путям.

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

Но одними только подписчиками по почте сыт не будешь.

2. Мы создали специальный канал в Телеграм (заходите в гости https://t.me/SetRetail) в котором, автоматически публикуются сообщения:

• О новых статьях или обновлениях в контенте.

• О выпуске новых патчей и версий наших продуктов.

• Важные объявления о наших продуктах.

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

4. «Но и это еще не всё!», как любят говорить в шоу с магазином на диване. 

Неотъемлемой частью пиара контента является еще внутренняя раскрутка. У нас в компании развернуто отечественное решение Битрикс24, поэтому важно, чтобы новости о версиях выпущенного продукта и новостях о статьях ревела из каждого утюга. Какая-то часть компании использует в своей работе только CRM, поэтому им очень удобно, что такие уведомления они получают прямо в живую ленту Битрикса24. И, конечно, на корпоративные адреса.

В чем профит 

Благодаря порталу поддержки мы сократили коммуникацию между нашими партнерами/клиентами — и сотрудниками поддержки CSI, это факт. 

Я уже писал, что портал поддержки должен снижать нагрузку на саппорт. Так и есть. Во многих случаях, когда поступает заявка, наши постоянные партнеры, ориентируясь на инструкции портала, сразу пишут, что не смогли пройти такие-то шаги по инструкции, споткнулись. Да, бывает и такое, но это дает очень хороший задел по времени сотруднику ХедпДеска, который сразу может сориентироваться и понять, что происходило. Ну и классическая ситуация — зачастую сотрудник ХелпДеска просто дает ссылку на документацию портала поддержки, сокращая время на консультацию. 

Всегда приятно получать отзывы, которые говорят о том, что клиенты и коллеги действительно ценят наш труд. Их много. Вот недавно коллега написал: «Саша, тебе и твоим коллегам от ***** (здесь название одной известной торговой сети) персональная благодарность и низкий поклон за качество документации на нашей вики. Очень довольны степенью подробности и доступности описаний. Интереса ради сажали не самых сведущих в API и прочих технических темах людей и те без проблем web-сервисами получали с лету нужные данные. Просто у них пока никакого BI сейчас нет и понять количество чеков и покупателей на майских праздниках — это целая задача». 

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

В такие моменты понимаешь, что все не зря. 

Что ж. Надеюсь, вам было интересно в моей компании, на этом не прощаемся, скоро увидимся. Буду рад ответить на вопросы.