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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

---

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

---

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

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

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

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

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

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

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

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

Какие критерии вы используете, когда ставите или принимаете задачу на технический документ?
public poll

Знаю и использую эти критерии – 9
👍👍👍👍👍👍👍 60%
@Elaneor, @solntseN, @SoNiQQQue, @Nick_Volynkin, @Lananovikova, @kipkaev, @annacraneo, Алена, Sagi

Теперь знаю и буду использовать – 5
👍👍👍👍 33%
@Andreichernov, @Altenrion, @IharReznichenka, @Lytkini, @dr_heart

Использую другие критерии, расскажу в @docsascode – 1
👍 7%
@mnmlsniper

Не буду использовать (интересно, почему → @docsascode)
▫️ 0%

👥 15 people voted so far.

Илья Бирман критикует нумерованный список с причинами отказа:

Сайт перечисляет причины, по которым деньги пользователя до него не дошли. Из-за использования списка с точками кажется, что случились все эти беды. Если заменить список на вариант со скобками 1) 2) 3) 4) 5), будет читаться чуть легче. Никто не знает, почему так, но список с точками скорее воспринимается как элементы, соединённые союзом «и», а со скобками — союзом «или».

​​Думаю, что нужно пойти дальше и сменить список на маркированный. Номера подразумевают порядок. Маркеры — это выбор независимых вариантов. Смотрите, что получается:

​​Как правильно закодить локализуемые строки

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

Общий принцип номер один: предложения переводятся целиком, поэтому и в коде они должны быть целиком.

Например, в интерфейсе есть такая строка:

Nick's account is suspended

Здесь есть имя пользователя, его нужно подставить в шаблон. Наивный программист напишет так:

user + "'s account was suspended"

Переводчик получит только строку в кавычках и перведёт, как сможет:

Nick учётная запись заблокирована

Это звучит ужасно, поэтому переводчик может поменять смысл в угоду грамматике:

Nick, ваша учётная запись заблокирована

Это ещё хуже, потому что текст адресован не владельцу учётной записи.

Как правильно

В коде всё предложение должно быть одной строкой-шаблоном:

"{name}'s account is suspended".format(name=user)

Теперь переводчик сможет поставить переменную в нужное место:

— "Учётная запись {name} заблокирована"  
— "Cuirtear cuntas {name} ar fionraí"  
— "គណនីរបស់ {name} ត្រូវបានផ្អាក"  


Одно предложение = одна строка-шаблон

#l10n_docops

---

Если вы давно это знали или просто хорошо разбираетесь в локализации — заходите в чат @docsascode, поделитесь опытом и болью.

На фото — доска после обсуждения на митапе. На ней есть кусочки двух ещё не опубликованных постов. 😉

Технический переводчик для хардкорных текстов


Раньше я участвовал в переводе ежемесячных постов про GitLab для Хабра, это было очень интересно и я прокачался в переводах. Вот мой любимый перевод: GitLab Flow

Теперь времени на это не хватает и я только заглядываю в качестве технического редактора и subject matter expert.

А в nadmosq.ru нужны новые технические переводчики. Ребята занимаются настоящими техническими текстами — программирование и девопс, никаких обзоров техники или прочего треша.

Если вам это интересно — напишите мне (@Nick_Volynkin), расскажу о деталях. Знаете хороших переводчиков? Пожалуйста, свяжите нас.

#l10n_docops

Нашёл отличный канал про тексты в интерфейсах, рекомендую: @tinywordsmakemagic

Вот ещё одна иллюстрация ошибки, утекающей в интерфейс (см. t.me/docops/57)

Когда эксперты Тотального диктанта, преподаватель Института филологии, журналистики и межкультурной коммуникации Южного федерального университета и IT-координатор не подумали о тексте ошибки

Привет всем, кто тащит легаси в светлое будущее!

Александр Парень рассказывает, как сделать из старого Confluence Server новый Confluence Cloud: http://telegra.ph/Migriruem-kontent-s-Confluence-41-na-oblako-07-26

Вот ещё его доклад о том, как готовить Confluence: https://youtu.be/TLOvJAb-E2Y

​​Задача номер 1

Я хочу сыграть с вами в одну игру.

Вот три абзаца текста из очередного релизного поста GitLab 11.1. Как вы считаете, можно ли в них что-то улучшить? Есть ли в них общие ошибки?

Первый абзац не связан по смыслу со вторым и третьим. Я поставил их рядом ради иллюстрации.
Если вам нужен контекст, вот пост целиком: GitLab 11.1 released with Security Dashboards and enhanced code search.

Напишите ответ мне — @Nick_Volynkin. Тех, кто раньше всех найдёт ошибки, я публично похвалю и/или угощу чашкой кофе, когда буду с вами в одном городе.

#docops_challenge

​​Консистентность

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

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

Вывод: Однородные объекты должны выглядеть одинаково, разные — по-разному.

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

— Элементы интерфейса выделены внутристрочным кодом, полужирным или никак не выделены.
— Названия панелей могут быть с заглавной или строчной буквы: Security Dashboard, performance dashboard.

Неконсистентное оформление первым заметил тестировщик @oneumyvakin, это было ещё вчера вечером. А сегодня он начал работать в Plesk. Совпадение? Да, совпадение.

Неконсистентный стиль в названиях дашбордов первым заметил @arvikon в чате @docsascode.

На фото мы с Олегом @oneumyvakin на кухне Plesk, у него в руках обещанный мной кофе.

А текст в задаче неконсистентен не только по оформлению. О второй ошибке напишу завтра.