Хотя второй по счету митап Write the Docs Moscow состоялся уже месяц назад, опубликовать отчет и краткие конспекты докладов никогда не поздно. Мы успели обсудить ну практически все: от документирования RESTful API до профессиональных траекторий техписателя.
Митап, кстати собрал не только «техписательское гетто», но и широкий круг других специалистов, кто так или иначе работаетиспытывает боль с документацией на проекте: тимлиды, аналитики, тестировщики и даже один технический директор.
Наш митап прошел 14 октября, воскресенье (в топ самых популярных вопросов о нем входил, «А почему именно в воскресенье?») в офисе компании IPONWEB. Митапы Write the Docs проходят по всему миру от Бангалора до Сан-Франциско, от Лондона до Сеула, российская ветвь сообщества только набирает активность, но уже есть отделения в Москве, Питере и Новосибирске.
Антон Телин, Зачем и как мы делаем видеоинструкции
Видео
Слайды
Антон руководит отделом технической документации в компании СБИС, которая делает систему электронного документооборота. Почему видео? Люди не хотят читать инструкции, они хотят решить проблему. Люди хотят, чтобы им доступно и наглядно объяснили.
Видео – удобный способ преподнести большой объем информации, реализовать сценарий в динамике, последовательность действий. Также можно акцентировать внимание пользователя музыкой или озвучанием.
Если продукт сложный и у него не продуманный интерфейс, то без визуальной части сложно донести его суть до пользователя. Плюс в том, что это позволяет снизить затраты на техническую поддержку.
Минусы – подходит не для всех форматов публикации, сложно встроить в doc и pdf. Сложно искать по нему. Видео высокого качества делать дороже.
Еще одна актуальная проблема – это сложность обновления, но комапания Антона решила эту проблему. Они отказались от записи скринкастов (захвата экрана) в пользу высококачественных скриншотов.
Компания использует два формата видео:
1. Видео инструкция – это последовательность действий, подробно и по шагам. Длительность ~ 2 минуты. 1 инструкция – это 1 проблема. В ней не рассказывается обо всех окнах, галках, кнопках. Затем добавляется озвучание, фоновая музыка, текстовые пояснения, титры.
2. Объясняющий ролик. Это что-то на стыке инструкции и презентации продукта. Общее представление без технических деталей, решает несколько проблем или сценариев. В таком ролике могут присутствовать люди и анимация. Длительность 2-3 минуты.
Инструменты: Adobe Premiere и Adobe After Effect для монтажа, Adobe Audition для звука, Photoshop и Snagit для редактирования изображений. Собирается проект из множества скриншотов, не актуальные или ошибочные потом легко подменить. Далее добавляется прорисовка движения мыши, анимация, звук.
Для озвучания они решили использовать не профессиональных дикторов, так как они звучали слишком формально, поэтому используют голос сотрудника компании Ильи, который поет в metalcore группе. После блока информации обязательно дается 2 секунды паузы на осмысление.
Ролики публикуются как на собственном хостинге и на Youtube. Минус – это блокировка его многими компаниями по соображениям безопасности.
Конечно же, в СБИС собирают всю доступную статистику: средняя продолжительность просмотра, лайки, обращения в техподдержку, которые были закрыты с помощью ссылки на видео.
Николай Волынкин, Технический писатель версия 2.0.1
Видео
Слайды
Это повтор или лучше сказать – дополнение к докладу с конференции SECR. Николай долго наблюдал за техническими писателями и заметил, что они не всегда умеют обосновать и измерить свою пользу, руководители, которые ставят им задачи – тоже.
Есть какие-то смежные задачи, которые технические писатели могли бы решать. Николай рассказал, какие же карьерные траектории и наборы навыков есть у техписов, как продать бизнесу ваши новые задачи.
5 ролей, которые может исполнять технический писатель:
1. Docops – devops для документации, писатель/программист, он умеет автоматизировать генерацию, проверку, выгрузку документации, обучает команду с этим работать и перестраивает все процессы вокруг нее.
Польза – снижение ручного труда, экономия ресурсов, скорость доставки фич выше.
2. UX-писатель – специалист по написанию текстов в интерфейсах.
Польза – дизайнеры, пиэмы, аналитики или фронтенд-разработчики не всегда понимают, как правильно писать, как доносить до пользователя фукнции, кнопки, переходы. Тексты пишутся по принципу кто первый встал, того и тапки. Удобство интерфейса, снижение времени на техподдержку.
3. Технический евангелист, он рассказывает о технологиях, взаимодействует с сообществом, формирует его.
Польза – повышение доверия и лояльность к компании, к продукту, упрощение найма, HR бренд.
4. Knowledge Manager – исследует, как компания производит, хранит и передает знания. Налаживает эти процессы, чтобы знания не утекали.
Польза – снижение bus factor, скорость адаптации сотрудников, как новичков, так и при переходах внутри, переиспользование знаний, снижение рисков.
5. Documentation Owner – PM и аналитик для документации. Он выстраивает всю систему коммуникации и взаимодействия пользователей в документацией.
Польза опять же в снижении затрат на поддержку.
В процессе обсуждения мы вспомнили такую комплексную роль, как контент-менеджер, которая не была отмечена в докладе.
Константин Валеев, Foliant
Видео
Слайды
Константин из Рестрим рассказал об инструменте Foliant — реализации docops workflow на основе языка Markdown. Год назад в рамках мини-Гипербатона в Яндексе Константин уже рассказывал про Foliant, и с тех пор поменялось очень многое.
Документация пишется в MD файлах, причем лежащих в разных местах, инструмент поддерживает continious integration, автоматическую сборку, также он позволяет расширять MD по их вкусу.
Требования: нужно отдавать docx для заказчиков и PDF с хорошей типографикой, иметь человекочитамые исходники (не XML).
Под капотом используется универсальный конвертер Pandoc, сверху накручены скрипты на Python, bash. Но во временем количество скриптов росло, поэтому их переписали в единое, монолитное приложение.
Из монолита затем сделали модульную структуру с ядром, управляющим сборкой, препроцессоры, которые конвертируют MD для работы сборщиков, и сами сборщики.
Foliant – это, по сути, клей между хорошими инструментами (mkdoc, pandoc, slate, latex). Сейчас они стараются научить потреблять источники документации из разных форматов.
В папке проекта лежит конфиг со структурой итогового документа, стилями и собственно MD файлы, далее препроцессоры берут исходные MD файлы и применяют к ним обработку, чтобы сделать MD нужного вида в стиле all.md (md в стиле foliant), далее сборщики итоговых документов (pandoc, mkdoc) делают из них таргеты (документы). После сборки MD запускаются линтеры, проверяющие синтаксис. Также отправляются почтовые уведомления о сборках или ошибках.
Все это можно собрать в Docker, чтобы все пакеты поставить одним образом, а не отдельно каждый.
Foliant поддерживает продвинутые include, умеет вытаскивать куски кода из Gitlab/Github и картинки с макетами из Simpli, умеет в отрисовку диаграмм, подстановку параметров в тексте, условные операторы.
Никита Самохвалов, Исчерпывающая документация на RESTful API
Видео
Слайды
Никита Самохвалов, технический директор компании Нотамедиа рассказал, как они настроили генерацию API-документации на базе Open API 3.0.
Как и все, они начинали с Google Docs, но у него нет ни версионности, ни возможности создавать ветки. Затем стали просто писать MD файлы в репозитории, решилась проблема версионности и создания веток, но все было медленно. Тогда пришли к автогенерации.
К документации были следующие требования: наследование и переиспользование кусков документации, возможность дать ссылку на описания параметров и методов, информация о разграничении прав доступа, документация как код (синхронные деплои и изменения). Кроме того, документация не выкладывается публично, только для своей команды и команд разработки заканчиков.
Выбрали спецификацию OpenAPI 3.0. Почему? Она самая свежая, она поддерживает больше возможностей, хотя вокруг нее еще небольшая экосистема и экспертиза.
Они взяли инструмент shins (показывает MD файлы в красивом лэндинге с примерами запросов, описанием методов, параметров), widdershins (конвертер из yaml/json в MD), также они написали собственный пакет specker (устанавливает все нужные зависимости, работает через npm, также проверяет корректность структуры размещения файлов).
Установка окружения и сборка документации делаются одной строкой в консоли. В папку dependencies/ попадают файлы, которые нужно переиспользовать в каждом проекте, например, описание авторизации.
Никита также рассказал о том, как они работают с ветками в распределенной команде, когда ставится задача на обновление документации и, конечно же, о подводных камнях и сложностях, которые сопутствовали внедрению OpenAPI 3.0.
Светлана Новикова, Управление знаниями с помощью матрицы компетенций
Видео
Слайды
Светлана (это я, кстати) рассказала о том, как они в компании устроили перезагрузку кондовому инструменту из сферы управления персоналом, как матрица компетенций, в чем тут польза для управления знаниями, как инструмент помогает снизить bus factor, лучше онбордить новичков, даже найти части кода для рефакторинга.
Данила Медведев, «НейроКод»
Видео
Данила рассказал про понятный пока не всем и, возможно, опережающий наше время, инструмент для моделирования и хранения знаний под названием НейроКод.
Этот инструмент полезен всем, кто занимается проектированием ИТ-систем. В частности, Данила предлагает отказаться от документоцентричных систем. Любая система рассматривается как сеть, по нодам которой передается какая-то информация. Этому принципу подчиняются все элементы системы – push updates, передача документов, передача обратной связи. Цель работы НейроКода — “сокращение непроизводительных затрат на обеспечивающие процессы и усиление коллективного интеллекта организации”.
Проект НейроКод вырос из решения задачи – как создать хорошее хранилище информации для команды или для себя, как создать модель информации. Прототип системы сделан и работает, сейчас обкатывается с помощью системных инженеров и бизнес-архитекторов. У системы масштабирумый интерфейс и основана она на фрактальной структуре данных. Она также основывается на идеях Дугласа Энгельбарта (это один из первых исследователей человеко-машинного интерфейса, автор концепций GUI, гипертекста и т.д.) 1960-х годов об Open Hyper-Document Systems (OHS), когда система не документоцентричная, а единая, то есть в ней реализованы все процессы человеческой деятельности.
P.S. В общем, лучше видео посмотрите.
Следующий митап Write the Docs Moscow состоится 7 декабря в офисе компании Positive Technologies, и пройдет он в формате Positive Authoring Tools Battle.
Митап, кстати собрал не только «техписательское гетто», но и широкий круг других специалистов, кто так или иначе работает
Наш митап прошел 14 октября, воскресенье (в топ самых популярных вопросов о нем входил, «А почему именно в воскресенье?») в офисе компании IPONWEB. Митапы Write the Docs проходят по всему миру от Бангалора до Сан-Франциско, от Лондона до Сеула, российская ветвь сообщества только набирает активность, но уже есть отделения в Москве, Питере и Новосибирске.
Антон Телин, Зачем и как мы делаем видеоинструкции
Видео
Слайды
Антон руководит отделом технической документации в компании СБИС, которая делает систему электронного документооборота. Почему видео? Люди не хотят читать инструкции, они хотят решить проблему. Люди хотят, чтобы им доступно и наглядно объяснили.
Видео – удобный способ преподнести большой объем информации, реализовать сценарий в динамике, последовательность действий. Также можно акцентировать внимание пользователя музыкой или озвучанием.
Если продукт сложный и у него не продуманный интерфейс, то без визуальной части сложно донести его суть до пользователя. Плюс в том, что это позволяет снизить затраты на техническую поддержку.
Минусы – подходит не для всех форматов публикации, сложно встроить в doc и pdf. Сложно искать по нему. Видео высокого качества делать дороже.
Еще одна актуальная проблема – это сложность обновления, но комапания Антона решила эту проблему. Они отказались от записи скринкастов (захвата экрана) в пользу высококачественных скриншотов.
Компания использует два формата видео:
1. Видео инструкция – это последовательность действий, подробно и по шагам. Длительность ~ 2 минуты. 1 инструкция – это 1 проблема. В ней не рассказывается обо всех окнах, галках, кнопках. Затем добавляется озвучание, фоновая музыка, текстовые пояснения, титры.
2. Объясняющий ролик. Это что-то на стыке инструкции и презентации продукта. Общее представление без технических деталей, решает несколько проблем или сценариев. В таком ролике могут присутствовать люди и анимация. Длительность 2-3 минуты.
Инструменты: Adobe Premiere и Adobe After Effect для монтажа, Adobe Audition для звука, Photoshop и Snagit для редактирования изображений. Собирается проект из множества скриншотов, не актуальные или ошибочные потом легко подменить. Далее добавляется прорисовка движения мыши, анимация, звук.
Для озвучания они решили использовать не профессиональных дикторов, так как они звучали слишком формально, поэтому используют голос сотрудника компании Ильи, который поет в metalcore группе. После блока информации обязательно дается 2 секунды паузы на осмысление.
Ролики публикуются как на собственном хостинге и на Youtube. Минус – это блокировка его многими компаниями по соображениям безопасности.
Конечно же, в СБИС собирают всю доступную статистику: средняя продолжительность просмотра, лайки, обращения в техподдержку, которые были закрыты с помощью ссылки на видео.
Николай Волынкин, Технический писатель версия 2.0.1
Видео
Слайды
Это повтор или лучше сказать – дополнение к докладу с конференции SECR. Николай долго наблюдал за техническими писателями и заметил, что они не всегда умеют обосновать и измерить свою пользу, руководители, которые ставят им задачи – тоже.
Есть какие-то смежные задачи, которые технические писатели могли бы решать. Николай рассказал, какие же карьерные траектории и наборы навыков есть у техписов, как продать бизнесу ваши новые задачи.
5 ролей, которые может исполнять технический писатель:
1. Docops – devops для документации, писатель/программист, он умеет автоматизировать генерацию, проверку, выгрузку документации, обучает команду с этим работать и перестраивает все процессы вокруг нее.
Польза – снижение ручного труда, экономия ресурсов, скорость доставки фич выше.
2. UX-писатель – специалист по написанию текстов в интерфейсах.
Польза – дизайнеры, пиэмы, аналитики или фронтенд-разработчики не всегда понимают, как правильно писать, как доносить до пользователя фукнции, кнопки, переходы. Тексты пишутся по принципу кто первый встал, того и тапки. Удобство интерфейса, снижение времени на техподдержку.
3. Технический евангелист, он рассказывает о технологиях, взаимодействует с сообществом, формирует его.
Польза – повышение доверия и лояльность к компании, к продукту, упрощение найма, HR бренд.
4. Knowledge Manager – исследует, как компания производит, хранит и передает знания. Налаживает эти процессы, чтобы знания не утекали.
Польза – снижение bus factor, скорость адаптации сотрудников, как новичков, так и при переходах внутри, переиспользование знаний, снижение рисков.
5. Documentation Owner – PM и аналитик для документации. Он выстраивает всю систему коммуникации и взаимодействия пользователей в документацией.
Польза опять же в снижении затрат на поддержку.
В процессе обсуждения мы вспомнили такую комплексную роль, как контент-менеджер, которая не была отмечена в докладе.
Константин Валеев, Foliant
Видео
Слайды
Константин из Рестрим рассказал об инструменте Foliant — реализации docops workflow на основе языка Markdown. Год назад в рамках мини-Гипербатона в Яндексе Константин уже рассказывал про Foliant, и с тех пор поменялось очень многое.
Документация пишется в MD файлах, причем лежащих в разных местах, инструмент поддерживает continious integration, автоматическую сборку, также он позволяет расширять MD по их вкусу.
Требования: нужно отдавать docx для заказчиков и PDF с хорошей типографикой, иметь человекочитамые исходники (не XML).
Под капотом используется универсальный конвертер Pandoc, сверху накручены скрипты на Python, bash. Но во временем количество скриптов росло, поэтому их переписали в единое, монолитное приложение.
Из монолита затем сделали модульную структуру с ядром, управляющим сборкой, препроцессоры, которые конвертируют MD для работы сборщиков, и сами сборщики.
Foliant – это, по сути, клей между хорошими инструментами (mkdoc, pandoc, slate, latex). Сейчас они стараются научить потреблять источники документации из разных форматов.
В папке проекта лежит конфиг со структурой итогового документа, стилями и собственно MD файлы, далее препроцессоры берут исходные MD файлы и применяют к ним обработку, чтобы сделать MD нужного вида в стиле all.md (md в стиле foliant), далее сборщики итоговых документов (pandoc, mkdoc) делают из них таргеты (документы). После сборки MD запускаются линтеры, проверяющие синтаксис. Также отправляются почтовые уведомления о сборках или ошибках.
Все это можно собрать в Docker, чтобы все пакеты поставить одним образом, а не отдельно каждый.
Foliant поддерживает продвинутые include, умеет вытаскивать куски кода из Gitlab/Github и картинки с макетами из Simpli, умеет в отрисовку диаграмм, подстановку параметров в тексте, условные операторы.
Никита Самохвалов, Исчерпывающая документация на RESTful API
Видео
Слайды
Никита Самохвалов, технический директор компании Нотамедиа рассказал, как они настроили генерацию API-документации на базе Open API 3.0.
Как и все, они начинали с Google Docs, но у него нет ни версионности, ни возможности создавать ветки. Затем стали просто писать MD файлы в репозитории, решилась проблема версионности и создания веток, но все было медленно. Тогда пришли к автогенерации.
К документации были следующие требования: наследование и переиспользование кусков документации, возможность дать ссылку на описания параметров и методов, информация о разграничении прав доступа, документация как код (синхронные деплои и изменения). Кроме того, документация не выкладывается публично, только для своей команды и команд разработки заканчиков.
Выбрали спецификацию OpenAPI 3.0. Почему? Она самая свежая, она поддерживает больше возможностей, хотя вокруг нее еще небольшая экосистема и экспертиза.
Они взяли инструмент shins (показывает MD файлы в красивом лэндинге с примерами запросов, описанием методов, параметров), widdershins (конвертер из yaml/json в MD), также они написали собственный пакет specker (устанавливает все нужные зависимости, работает через npm, также проверяет корректность структуры размещения файлов).
Установка окружения и сборка документации делаются одной строкой в консоли. В папку dependencies/ попадают файлы, которые нужно переиспользовать в каждом проекте, например, описание авторизации.
Никита также рассказал о том, как они работают с ветками в распределенной команде, когда ставится задача на обновление документации и, конечно же, о подводных камнях и сложностях, которые сопутствовали внедрению OpenAPI 3.0.
Светлана Новикова, Управление знаниями с помощью матрицы компетенций
Видео
Слайды
Светлана (это я, кстати) рассказала о том, как они в компании устроили перезагрузку кондовому инструменту из сферы управления персоналом, как матрица компетенций, в чем тут польза для управления знаниями, как инструмент помогает снизить bus factor, лучше онбордить новичков, даже найти части кода для рефакторинга.
Данила Медведев, «НейроКод»
Видео
Данила рассказал про понятный пока не всем и, возможно, опережающий наше время, инструмент для моделирования и хранения знаний под названием НейроКод.
Этот инструмент полезен всем, кто занимается проектированием ИТ-систем. В частности, Данила предлагает отказаться от документоцентричных систем. Любая система рассматривается как сеть, по нодам которой передается какая-то информация. Этому принципу подчиняются все элементы системы – push updates, передача документов, передача обратной связи. Цель работы НейроКода — “сокращение непроизводительных затрат на обеспечивающие процессы и усиление коллективного интеллекта организации”.
Проект НейроКод вырос из решения задачи – как создать хорошее хранилище информации для команды или для себя, как создать модель информации. Прототип системы сделан и работает, сейчас обкатывается с помощью системных инженеров и бизнес-архитекторов. У системы масштабирумый интерфейс и основана она на фрактальной структуре данных. Она также основывается на идеях Дугласа Энгельбарта (это один из первых исследователей человеко-машинного интерфейса, автор концепций GUI, гипертекста и т.д.) 1960-х годов об Open Hyper-Document Systems (OHS), когда система не документоцентричная, а единая, то есть в ней реализованы все процессы человеческой деятельности.
P.S. В общем, лучше видео посмотрите.
Следующий митап Write the Docs Moscow состоится 7 декабря в офисе компании Positive Technologies, и пройдет он в формате Positive Authoring Tools Battle.
