DocOps

Целеполагание технического документа

Авторы всех трёх комиксов из прошлого поста проделали отличную работу с целеполаганием:

— Комиксы написаны для конкретной аудитории. Ясон — воплощение целевого читателя. Он руководит админами в крупной компании, уже успел поработать с контейнерами и погибает под ворохом типичных проблем. Гера, воплощение автора, упоминает всё, что он уже должен знать, и подробно объясняет всё новое.

— Решают задачу читателя — понять основы сложной предметной области. После этого читатель сможет изучать её дальше или использует знания, чтобы принять решение. Все комиксы объясняют сложную тему, при этом развлекают и помогают удержать внимание. Думаю, начинать знакомство с man kubectl мне было бы гораздо тяжелее. Конечно, комикс не заменит документацию, но она решает совсем другие задачи.

— Решают задачу бизнеса. В первом комиксе Гера попутно продаёт читателю Google Cloud. Второй и третий приглашают на сайт компании DNSimple, которая предоставляет DNS и перепродаёт SSL-сертификаты.

Эти критерии целеполагания я когда-то узнал от Семёна Факторовича на курсе Advanced technical writing и с тех пор использую их для всех технических документов. Жанр документа может быть любой: комментарии в коде, пользовательская документация, статья на Хабре или пост в канале, который вы сейчас читаете.

Документация как комиксы

Когда мне было четыре или пять лет, мама подарила мне книжку комиксов «Откуда берутся дети». Я прочитал, всё понял и в следующие лет 7-10 знал точно больше своих сверстников. Конечно, потом были и другие источники, но тот комикс дал мне начальные знания и избавил от кучи недоразумений.

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

— «Приятного плавания с Kubernetes».
Древнегреческий мореплаватель Ясон теперь работает в IT и руководит отрядом боевых админов. Это сложнее, чем засевать поля драконьими зубами. Богиня Гера знакомит его с «κυβερνήτης», «рулевым». Конечно, Рулевой решает сразу все проблемы Ясона — это же сказка, а в сказке так бывает.

— Как работает DNS.
DNS-запрос путешествует в поисках IP-адреса.

— Как работает HTTPS.
Сертификот и другие звери рассказывают о том, как защитить сообщения в интернете от злонамеренных крабов.

---

Кстати, от того же корня, что и «кубернетес», образованы слова «губернатор» и «гувернёр».

Знаете другие примеры хорошей документации в картинках? Приходите обсудить их в @docsascode.

Волынкин Николай @Nick_Volynkin поднимает в своём канале @docops одну из фундаментальных проблем в современной разработки, актуальную для компаний любого размера, начиная от стартапов и заканчивая многослойными большими корпорациями: как замапить код и его изменения на требования бизнеса.

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

Кажется, что для этого нужно заранее выстраивать цепочку от коммитов к задачи в трекере и к общим документам уровня feature vision или контракта. Просто номера задачи в сообщении коммита не хватает — часто в задаче есть описание только на функциональном уровне, но не рассказано про значение для бизнеса.

Как замапить код и его изменения на требования бизнеса

Вопрос, который мы обсуждали с разными людьми на РИТ, Highload Siberia, в чате TeamLeadConf и на кухне в компании Plesk. И продолжаем обсуждать с Дмитрием Симоновым (@r2d2_e2e4, канал @ctorecords).

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

Приглашаю вас поделиться идеями и опытом в чате @ctorecordschat.

Обзорная статья про диаграммы-как-код

На Хабре сегодня опубликовали статью про PlantUML. Это текстовый формат для описания диаграмм и программа, которая делает картинку из текстового описания.

В комментариях, как это часто бывает, обсуждают позицию «документация не нужна, потому что есть код».

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

​​Документ готов, когда его начали дополнять

Продолжаю делиться идеями, добытыми на двух конференциях. Игорь Цупко, директор по R&D в компании Флант, так определяет definition of done для внутренней документации:

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

Если не дополняют — ищите причину:

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

— Люди не умеют/боятся пользоваться инструментами для дополнения документа. Да, так тоже бывает на ранних стадиях жизни. Каждого нужно провести за ручку или обеспечить механику, чтобы кто-то его проводил за ручку.

— Люди боятся вообще писать. Тогда нужно дать им в помощь писателя, чтобы тот оформлял их мысли.

— Документ бесполезен. Нужно вернуться к целеполаганию и понять, в чём задача. А потом наполнить документ пользой. Про целеполагание в документах я обязательно ещё расскажу.

— Документ никому не адресован. Для работы с этим аспектом есть отличный инструмент — граф коммуникаций. Это ещё одно сокровище, добытое на конференции и о нём тоже будет отдельный пост.

---

Игорь пишет заметки о руководстве командой и управлении знаниями в @lovely_it_hell.

Вот он что-то эмоционально рассказывает на митапе про управление знаниями в инженерных командах:

Конспекты про документацию и управление знаниями

Собрал в один список все конспекты с двух конференций. Старые посты со ссылками удалил.

— Документация: у кого что болит: митап на РИТ++,

— и ещё один на Highload++ Siberia.

— Польза от управления знаниями в компании.

— Управление знаниями в инженерных командах.

​​Польза и ценность технического писателя

«Я теперь хочу нанять себе техписателя, потому что знаю, что есть нормальные техписатели» — сказал мне на Highload Siberia Александр Титов, управляющий партнёр компании Экспресс 42.

Надеюсь, Александр ещё расскажет, какими он видит нормальных техписателей. Я вижу их так: «разговаривают на языке инженеров и бизнеса, понимают их глобальные задачи и хотят решать эти задачи».

Хочу больше писать о том, как технический писатель может приносить пользу в масштабе компании. Хочу сокращать разрыв между писателями, инженерами и бизнесом. Пожалуйста, поделитесь своими мыслями о пользе техписателя в чате @docsascode или напишите мне (@Nick_Volynkin). Этим вы очень поможете мне и моим коллегам. А мы постараемся быть полезными всей IT-отрасли.

На фото Александр зашёл к нам на стенд на Highload Siberia.

Про локализацию софта
https://www.youtube.com/watch?v=mIwkvkwq96o

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

Самым первым систематичным и удобным подходом к решению задачи стал GNU GetText: https://ru.wikipedia.org/wiki/Gettext, хранение переводов в .po файлах или их модификациях.

За ним подтянулись аналогичные решения на практически всех платформах. Это или нативные решения на уровне стандартных классов, как сделано в Android и iOs или дополнительные библиотеки, как в многочисленных скриптовых и не только языках:

* Android - https://developer.android.com/guide/topics/resources/localization

* iOs -https://developer.apple.com/library/content/documentation/MacOSX/Conceptual/BPInternational/LocalizingYourApp/LocalizingYourApp.html

* php/Symphony - https://symfony.com/doc/current/components/translation.html, включающий в себе массу провайдеров поставщиков переводов, в том числе и https://api.symfony.com/4.0/Symfony/Component/Translation/Loader/MoFileLoader.html

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

Задача эта настолько непроста и зависит от множества людей и факторов, что, например, телеграмму пришлось даже запустить собственную платформу для переводов: https://translations.telegram.org/

Если же свою платформу разрабатывать не хочется, есть готовые решения:


* https://crowdin.com/
* https://gitlocalize.com/
* https://poeditor.com/
* https://localise.biz/

Они умеют экспортировать/импортировать в любые форматы, в т.ч. те, которые используются в профессиональных программах для переводчиков, и не всегда это .po

Так, например, для андроида вместо .po файлов используется аналог strings.xml, а для ios - Localizable.strings

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

Итого, true way для локализации является использование gettext или аналогов в стыковке с платформой по менеджменту переводов, умеющей экспортировать переводы в нужные форматы.

Про docops-подход к локализации пишет Дмитрий Симонов, CTO компании Дримсим.

Кроме перечисленных им платформ для локализации знаю ещё transifex.com и pootle.translatehouse.org

Если у вас есть опыт использования таких инструментов — поделитесь в @docsascode

​​Ошибки утекают в интерфейс

Бабушка пришла на остановку и ждёт автобус. Раньше она просто ждала и не знала, когда он придёт. Но теперь есть электронное табло, благодаря которому бабушка не знает ещё и что такое сервер, и почему он недоступен.

Это утечка: ошибка из мира кода попала в мир пользователя. Не надо так. Оборачивайте ошибки в понятную форму. Если нечего сказать пользователю — можно было бы вообще ничего не показывать.

В идеале сообщение об ошибке должно помогать пользователю решить его проблему. Об этом в следующем посте.

Сменил название на более компактное.

Channel name was changed to «DocOps / Docs as code»

​​​​А здесь, слева направо: автор этого канала, Римма Джаникян из оргкомитета конференции, Семён Факторович и Татьяна Фокина.

​​(фото терялось, пришлось опубликовать заново)

​​Пост благодарностей

За последний месяц мы, Сибирское сообщество техписателей, побывали сразу на двух крупных конференциях: РИТ++ и HighLoad++ Siberia.

На обеих конференциях мы провели митапы о документации и управлении знаниями, пообщались со множеством инженеров и технических менеджеров. А ещё наладили сотрудничество с организаторами других IT-сообществ по всей России.

Как мы туда попали? Нас пригласил Олег Бунин, организатор этих двух и ещё множества отличных конференций. Взял и подарил билеты нам и другим активистам сообществ. А на HighLoad ещё и выделил нам стенд в экспертной зоне. Спасибо Олегу и всему оргкомитету за помощь и сотрудничество!

Кстати, в Москву на РИТ++ я ездил в рабочее время и в командировку, как сотрудник компании Plesk. Ещё Plesk сильно помогает нам с митапами в Новосибирске. Спасибо за поддержку!

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

На фото Олег Бунин и Юлия Поповкина зашли на наш стенд в экспертной зоне.

Обсуждаем документацию с @docops на хайлоад сибирь.
Основная боль пришедших - в мотивации людей. Как будто все хотят, но не могут.

К сожалению, инженеры и менеджеры не заинтересованы в том, чтобы делиться своими знаниями. Это сложно, и вообще - зачем делать себя заменимым? Тогда ж в любой момент тебя уволят.
Самое смешное - того человека, который делает бизнес отказоустойчивым не уволят, это слишком ценно для бизнеса.
Но новичков к этой мысли надо подводить и заставлять.

Будет такая сфера, обязательно будет!

да пджите радоваться) скоро сольемся с аналитиками или тестировщиками и будет новая сфера - докопс или тестопс какой нибудь :)

Из чата @technicalwriters

Как начать внедрять фиксацию знаний в компании.

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

Как начать с самого начала?
Начнём с тезисов:
- люди не хотят, не любят и не будут документировать. Их придётся заставить и научить.
- люди не умеют в русский язык
- хороших экосистем для документации не существует, их надо будет строить. И они сейчас строятся выходцами из техписовой тусовки, но медленно. Люди пока не верят в финансовую отдачу от этой движухи.
- документация - это вещь _на стыках_ между людьми/ролями. Нет смысла делать документацию в тех местах, где стыка нет.

Подробно всю эту тему освещал тут: https://www.youtube.com/watch?v=NGiN3df_YGc
В том числе в видео вы найдёте пример структуры доки и объяснение того, какую структуру доки нужно построить именно вам.