Выпуск #12. Беседа с Ариной Балериной

Опубликовано 28.12.2023

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

Но под Новый год случилось чудо! Я нашёл такого эксперта, который может помочь мне донести нужную информацию до инженеров.

В сегодняшнем выпуске представляю запись беседы с Ариной - техническим коммуникатором с 20-летним опытом работы в IT.

Полезные ссылки

Книги:

«Разработка документации пользователя программного продукта» Юрий Кагарлицкий

«Пиши, сокращай» Максим Ильяхов и Людмила Сарычева

«Живой Как Жизнь» Корней Чуковский

«Беседы о русском языке (1963)» Корней Чуковский

Контакты Арины:

Сообщество технических писателей

Ник: @ArinaBallerina

Профиль ментора

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

Поделитесь подкастом с друзьями и коллегами

---

Расшифровка выпуска

Владимир Юсупов: Добро пожаловать в подкаст технического коммуникатора Техкомпод!

Меня зовут Владимир Юсупов. Я - технический коммуникатор и, по совместительству, ведущий данного подкаста.

На календаре 28 декабря 2023 года.

Выпуск номер двенадцать. Предновогодний выпуск с прекрасным настроением.

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

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

В сегодняшнем выпуске представляю запись беседы с Ариной - техническим коммуникатором с 20-летним опытом работы в IT.

Арина была техническим писателем в СберТехе, Яндексе и руководила разработкой документации ВКонтакте.

Арина очень хорошо известна в популярной и самой большой в России телеграм-группе для технических писателей, под ником Арина Балерина.

И наконец, Арина - просто замечательный собеседник. Мне было бесконечно приятно общаться с ней не только во время записи беседы, но и в процессе подготовки.

Итак, запись беседы с Ариной. Приятного прослушивания!

Привет, Арина! Добро пожаловать в подкаст технического коммуникатора!

Арина Балерина: Привет, Володя! Фантастическое по красоте название подкаста.

Владимир Юсупов: Арина, ты хорошо известна в сообществе технических писателей. Аудитория подкаста на текущий момент состоит в основном из инженеров. В самом начале выпуска я представил тебя слушателям достаточно кратко. Перед тем, как мы перейдем к основной части беседы, могла бы ты немного рассказать о себе - где сейчас работаешь, чем занимаешься?

Арина Балерина: Я начну наверное с того, что немножко примажусь к аудитории. Потому что я честно училась пять с половиной лет на инженера. И один раз даже работала совсем чуть-чуть в инженерной компании. Но там мне дали писать документацию сразу и я ушла, потому что подумала, что мне хочется писать документацию в другом месте. Да, я честно училась на инженера-системотехника. Когда я училась, мне хотелось всё знать про системы управления.

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

Владимир Юсупов: Поздравляю!

Арина Балерина: Спасибо! И как ты догадываешься, за двадцать лет можно было много где поработать. Но начнём с конца.

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

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

У тебя в подкасте есть список такой, что может подразумеваться под технической коммуникацией и, в целом, технический писатель с опытом поставит галочку “ага, это я делал - тексты писал для приложений и автоматизировал чуть-чуть, и вот это, и вот это…”

Владимир Юсупов: Арина, я вначале упомянул, что ты являешься администратором крупнейшего в России сообщества технических писателей. Я говорю про телеграм-группу “Технические писатели”. Не так давно я к ней присоединился. Периодически просматриваю сообщения и обсуждения.

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

Арина Балерина: Да, Володя, ты не ошибаешься. Спасибо, что спросил. Я сейчас расскажу про теги, но начну с культуры общения.

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

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

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

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

Это не канал. В канале довольно легко придумать теги и использовать их дальше. А в сообществе трудно предсказать, какие темы буду подниматься, трудно проанализировать даже. Можно выгрузить конечно весь корпус текстов, чисто технически это возможно. Но как ты будешь это анализировать?

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

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

Знаешь, какая там сложность ещё была? Теги - это же… Ты не можешь MVP - Minimum viable product - выпустить, а потом доделать, как с интерфейсом. Ошибся с названием кнопки, получил фидбэк, исправил. С тегами так нельзя. Потому что это сообщество огромное. Это не канал. Люди уже используют теги, нельзя сказать: “Извините, мы сейчас переименуем тег, уничтожим всё, что вы разметили до этого, ваши сообщения драгоценные.” Админы не могут править сообщения участников. Вот что участник написал, вот то и всё. Админы могут только удалять целиком.

Представляешь, как было страшно запускать это? А друг мы ошиблись? А вдруг не так надо было назвать теги? Было очень страшно.

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

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

Владимир Юсупов: Да, спрошу.

Арина Балерина: А я тебе скажу: “А сходите, пожалуйста, дорогие слушатели, в сообщество.”

Но я скажу не просто: “Сходите в сообщество и там спросите, кто-нибудь вам ответит, кто в этот момент онлайн.”

А я скажу вам: “Сходите в сообщество и по тегу #знание поищите. Там много рекомендаций - и книг, и документации, и подкастов, на которые можно ориентироваться.” Это же круто.

Владимир Юсупов: Арина, если продолжить тему профессии “Технический писатель”.

Ведь сама профессия появилась в России не так давно официально. Насколько я знаю, до сих пор нет учебных заведений, которые обучают студентов по программе “Технический писатель”, не берем в расчёт краткосрочные курсы.

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

Расскажи, пожалуйста, о поворотном моменте в твоей карьере - как ты стала техническим писателем?

Арина Балерина: Ты абсолютно прав, учебных заведений, которые готовят людей по специальности “Технический писатель”, нет. В учебных заведениях стали сейчас появляться курсы (не курсы в том смысле, что все люди могут прийти туда), а стали появляться учебные курсы для студентов.

Допустим, учатся люди на разработчика.

Владимир Юсупов: Факультативные какие-то (курсы)?

Арина Балерина: Нет-нет, я не знаю, есть ли кафедры прямо с таким названием, отдельные. Но может быть уже и есть.

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

Владимир Юсупов: Интересно. Я не знал, честно говоря.

Арина Балерина: Есть. Потихоньку-потихоньку образовываются такие островки компетенций.

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

У нас есть курсы для людей, которые хотят стать техническими писателями. Они открыты для всех. Это курсы, которые делает компания Семёна Факторовича. А вот учебных, чтобы прямо получить диплом можно было, нет.

И это одна из причин, почему техническое писательство - это такая последняя дверь, которую ещё можно открыть, чтобы войти в IT, не имея диплома, потому что ни у кого диплома нет. HR-ы не охотятся за людьми с определённым дипломом. У меня был диплом инженера. Они сейчас охотятся за людьми с определённым бекграундом, опытом и навыками.

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

Потом я работала в дизайн-студии, которая, вообще говоря, занималась сайтами, каталогами. У нас был IT-отдел и я была руководителем этого отдела. Маленький IT-отдел. “IT-менеджер” тогда моя должность называлась.

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

И я десят лет постоянно всё это делала вокруг технического чего-то и постоянно вокруг текста.

Потом внезапно, когда я стала в какой-то момент искать работу, я увидела, как сейчас помню, на хедхантере. Я внезапно увидела, что оказывается все мои компетенции и мое желание, чем дальше заниматься, прекрасно укладывались в название такое классное “Технический писатель”. Писатель. Так приятно. Знаешь, как в анекдоте получилось. Я всю жизнь к этому шла, а потом случайно стала техписателем. Я тогда быстренько переименовала свой профиль в… Сейчас называется Хабр Карьера, тогда было что-то другое, я сейчас не помню что, но такой сайт для айтишников с профилями. Я переименовалась там. Как сейчас помню, я открываю там почтовый ящик и мне пишут из Яндекса и спрашивают, не хочу ли я попробоваться к ним туда. Да, конечно же я хотела.

Работая ещё в дизайн-студии, я научилась отличать хорошие тексты от плохих. И на тот момент нашими кумирами были Яндекс и Артемий Лебедев, кстати, который Ководство писал. Кто-то помнит может быть. Тогда они были нашими кумирами и мы всегда смотрели: “А как в Яндексе пишут? А как в Яндексе номера телефонов пишут? А как Артемий Лебедев номера телефонов пишет?” Потому что в дизайн-студии у тебя часто какой-нибудь адрес нужно правильно написать.

Я стала редактором-самоучкой. И когда я стала в Яндексе техписателем, я уже знала про текст, как писать. Но я тогда взяла себе техническую часть, потому что программированием я не занималась эти десять лет. У меня в институте был всего один курс по C++ полгода. И всё. Так как я - инженер, мне не давали много программирования. Инженер-системотехник.

В Яндексе был такой новый вызов для меня, когда я всех моих знаний о тексте хватало, но мне не хватало технических знаний, потому что я сразу стала документировать какие-то суровые вещи - API, распознавание речи. На тот момент вообще это на переднем крае было. Я была первым техписателем, который выпустил документацию как раз для ребят, для СпичКита (Yandex SpeechKit). У них до этого не было документации. С этого момента я стала себя называть техническим писателем. Я конечно очень благодарна этому времени в Яндексе, когда я училась у команды. Там была очень крутая команда на тот момент. И мне, можно сказать, повезло войти в профессию вот так.

Владимир Юсупов: Очень интересно. Я кстати знаю (такой факт). Ты рассказала о программировании. Если не ошибаюсь, ты любишь питонить иногда.

Арина Балерина: Я не буду врать. Я это делаю (питоню) раз в несколько лет в перерывах между работой.

В какой-то момент у меня было свободное время и я решила, что я создам телеграм-бота, потому что Телеграм был в моде. И боты только-только появились, а искусственного интеллекта ещё не было. По крайней мере, так широко, как сейчас, последние два года.

А я думаю: “Я хочу бота, который бы на вопросы отвечал.” Вернее, он не отвечает на вопросы, а поддерживает диалог. Я придумала бота. А кто будет его писать? Я же и буду. Написала небольшого бота диалогового на питоне. И базы данных попробовала, мне так нравилось это всё. Захостить же его надо было как-то. Закончила этот проект и больше не притрагивалась, если честно.

Владимир Юсупов: Опыт остался.

Арина Балерина: Знаешь, технический писатель, который на одну тему пишет - это роскошь. Мне пришлось за всё время выучить несколько языков программирования до уровня “Я могу написать простенькую программу” и мне пришлось их забыть.

Технический писатель, когда пишет документацию, должен понимать, что ему прислали в примере. Это сейчас он у ChatGPT может спросить. Тогда не мог. Пришлось сначала несколько дней учиться писать этот “Hello, World” на новом незнакомом языке, чтобы потом понимать, что за пример тебе прислали. При этом программировать на нём не нужно, по большому счёту, уметь, потому что это надо пять лет (учиться), а зачем, если тебе всего лишь нужно понимать, что нормальный пример или нет, что тебе прислали разработчики.

Владимир Юсупов: Да, интересно.

Арина, давай немножко поговорим про процесс или концепции подготовки документации.

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

Арина Балерина: В силу такой общей эрудиции айтишной, да, но не скажу, что я с этим работала.

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

Допустим у предприятия есть несколько (учетных) систем - 1С в одном (подразделении), 1С в другом (подразделении) и эксельки в третьем, условно говоря. Хранилище данных объединяет все эти данные в едином месте, едином хранилище. Хранилище используется в качестве единого источника правды или истины различными бизнес-направлениями компании для принятия каких-то управленческих решений.

Если провести аналогии с подготовкой документации, можно ли применить концепцию единого источника к документации и в чём эта концепция заключается?

Арина Балерина: Интересно про хранилища данных. Может быть, тебя расстрою, процитировав известный советский фильм, в котором была такая фраза “Всё уже придумано до нас.” Да, хотелось бы изобрести этот термин прямо сейчас “единый источник”. Но уже есть он. Доклады на эту тему есть. И есть такая концепция, такой подход к разработке документации и по аналогии с единым хранилищем данных, действительно, единое хранилище, но при этом не просто база знаний.

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

Что же такое будет единый источник? Это, когда мы перерабатываем эту базу знаний, стараясь делать так, чтобы было переиспользование фрагментов текстов, и дорабатываем её так, чтобы у нас были любые выходные форматы, которые мы хотим. Чтобы не было такого, что нанимается специально технический писатель, который занимается тем, что просто из этой базы знаний берёт и копирует тексты в Ворд (Microsoft Word), делает документы в Ворде. Этого не нужно, здесь возможна полная автоматизация, то есть этого человека можно заменить. Достаточно добавить некоторое количество скриптов. Вообще, из Конфлюенса много разных выходных форматов разных получить. Вы можете сделать определённый CI/CD (Непрерывная интеграция - Continuous Integration - и непрерывная поставка -Continuous Delivery). И у вас получится несколько выходных форматов. Это часть похода “Единый источник”, когда у вас есть единый источник знаний и при этом множество выходных форматов.

В своё время эту задачу прекрасно решала, и сейчас решает, просто когда-то она была популярна, сейчас уже меньше, DITA XML. Может кто-то слышал. Это и язык, и фреймворк, и концепция, и подход, и набор технических средств, которые позволяют сделать так, чтобы у вас из разных кусочков собирался любой документ, который вы хотите. Вторая часть идеи “Единый источник” - это переиспользование текстов. В DITA это было реализовано, вот попробуйте сейчас представить, что у вас есть xml, есть xml-тег, который вы сами как-то назвали. Допустим, у него есть атрибут - скрыть или показать. И вы можете скрывать и показывать по любому заданному вами правилу. Можно, например, хранить в одном документе русский и английский переводы. Фильтруя по тегам, делать русские документы или английские, когда вам нужно. Или можно скрывать какую-то информацию для определённого пользователя - кому надо вот это видеть, а кому-то вот это. А документ один. Это единый источник, переиспользование. В Конфлюенсе, кстати, тоже можно такое сделать.

Я когда работал в компании Bitfury, я была единственным человеком с должностью “Технический писатель”, а вокруг меня были системные аналитики. Они писали очень много документов - ТЗ на системы. Это была проектная компания. Мы продавали автоматизацию. Системные аналитики как раз ходил в тот Конфльюенс, который я для них создала. Они наполняли его, в том числе. Но в чём было ноу-хау для них. Во-первых, создала глоссарий, это уже опять единый источник правды, в данном случае, потому что у нас есть один глоссарий, куда все устремляются (посмотреть), что там написано. Во-вторых, я подключила ряд макросов, которые позволили нам переиспользовать контент. У меня бы определённый пул переменных, можем так назвать. Например, если у меня N=15, то одновременно N=15 во многих документах. А из Конфлюенса генерились как раз документы, шаблоны документов.

Понятно примерно как может выглядеть единый источник?

Владимир Юсупов: Да.

Арина Балерина: То есть это переиспользование и настройка автоматизации, чтобы разные выходные форматы были.

Владимир Юсупов: Арина, когда ты сейчас рассказывала про единый источник и Конфльюенс, ты мне напомнила боль, которую мы пережили недавно и, в принципе, ещё проживаем её.

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

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

Уверен, ты представляешь трудоемкость поддержания документации в актуальном состоянии, или неактуальном состоянии.

Арина Балерина: Хотя бы в состоянии.

Владимир Юсупов: Да, в состоянии, что это есть вообще. Эти бесконечные потоки писем с вложенными файлами пользователям, от пользователей и т.д.

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

Понятно, что Конфльюенс - не идеал, но для нас это значительный прогресс в части документации. Мы не только работаем с (более удобным) инструментов, но и перестраиваем процессы работы с документацией.

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

Не могла бы ты немного пояснить этот термин и дать однозначное определение того, что в компании применяется подход “Документация как код”?

Арина Балерина: Интересную тему ты затронул. Отрадно слышать, что есть такие люди, как ты, для которых граница проницаема и знания из других областей ты стараешься переносить на свою предметную область.

Я хочу здесь сначала выступить, может быть, адвокатом даже Ворда, или хотя бы не адвокатом… У меня есть подозрения, так как я вначале сказала, что я тоже немножечко инженер. У меня есть подозрение, что истоки того, что эта работа в Ворде законсервировалась…

Говорят ли в твоей среде такую фразу: “Работает - не трогай”? Такая инженерная (фраза).

Владимир Юсупов: Да, каждый день.

Арина Балерина: Мудрость, передающаяся из уста в уста. Работает - не трогай.

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

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

У нас есть “Работает - не трогай”, а с другой стороны, у тебя, например, ощущения, что уже пора меняться, потому что есть проблемы, какое-то количество проблем накопилось. Если бы это действительно работало, ничего менять не нужно было. Но это же не работает. Эта куча документов, это согласование. Это те места, где тратиться человеческий мозг.

Я сейчас отвечу на вопрос про docs-as-code. Я пытаюсь такую подводку сделать, немножко мотивационную, и заинтересовать инженеров с какой стороны.

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

Вот docs-as-code - это одновременно и про конкретные инструменты и процессы.

Как он появился? Это концепция. Давай так скажем, это ни какой-то стандарт. Нет, это не те стандарты, которые мы видим в вебе, когда у нас есть протоколы стандартизированные. Единственный пример, который можно привести - REST. Если знаешь такой термин REST API.

Владимир Юсупов: Да, конечно.

Арина Балерина: Это то, что везде есть. Мы это везде видим. Мы REST API видим постоянно, пользуемся ими. Их проектируют, про них целые конференции (проводят). Но, на самом деле, стандарта нет. Есть концепция, идея, которая всем понравилась. Это вылилось в то, что существует ряд инженерных практик - как проектировать такие системы.

С docs-as-code, в целом, то же самое с поправкой только на один момент. Когда прозвучало слово “docs-as-code”, оно тоже на техписательской конференции прозвучало, на самом деле, всё уже было. Просто человек, который произнёс это слово, он сформулировал, понятно назвал. На самом деле, всё уже было. А что было?

Автоматизация нужна? Нужна. В документировании нужна? Нужна. Хотим делать документацию быстро, хотим делать документацию качественно. Быстро в каком смысле? Не просто - чем быстрее пишешь, тем лучше, а быстро в том смысле, чтобы она не отставала от продукта. Большая боль, когда документация сильно отстаёт от продукта, выпуска продукта. И это уже всё было, это всё работало. Дальше появилась вот эта формулировка, концепция, которую уже можно было искать, гуглить что это такое. И сейчас ещё можно спрашивать у ChatGPT.

Это по твоему вопросу про однозначность. Нельзя однозначно сказать: “Вот у вас docs-as-code, а у вас - нет.” Это не один-ноль. Это некий спектр. Я так долго говорю, люди ждут (и думают): “Когда-нибудь скажи уже, что такое docs-as-code то…” Дело в том, что я не то, что не могу, а не хочу давать формальное определение.

Мы уже поговорили про то, что это концепция, что слово появилось уже тогда, когда всё уже работало в конкретно взятых компаниях. Не так, что сначала слово появилось, а потом все стали делать docs-as-code. Нет, всё уже работало. Почему? Почему всё работало уже? Потому что… Вот мы с тобой проговорили про переиспользование текста. Люди, которые делали что-то похожее на docs-as-code, подумали: “А почему бы нам не переиспользовать инструменты и процессы?” Какие процессы?

Знакомы тебе понятия “Водопадная разработка”? Agile?

Владимир Юсупов: Да.

Арина Балерина: Это такие понятия из циклов разработки ПО, подходов к разработке ПО.

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

Когда появился Agile, он не сразу появился кстати, все сначала, как инженеры…

Ведь инженер же не стал бы разрабатывать машину по-другому? Конечно же сначала он долго думает, проектирует, всё проверяет, а потом уже только машина выходит в конвейер. И так же стали делать ПО, а потом выяснили, что немножко не получается так. А почему не получается? Потому что мы не можем сразу знать, а что же в конечном итоге хотим получить. Это знают наши пользователи. Появился Agile и стали делать более короткие итерации, и как-то он так прижился.

Техписатели посмотрели на это и тоже такие (подумали): “Мы тоже хотим короткие итерации. Мы не хотим документацию писать-писать целый год, в потом у нас раз в год релиз документации. Потому что мы отстаём от продукта.” Ещё техписатели посмотрели на инструменты и поняли, что ребята-то не зря систему контроля версий себе сделали.

Вот здесь, кстати, хочу подчеркнуть, почему я, например, говорю система контроля версии, а не Git. В docs-as-code может быть что угодно на месте системы контроля версий - Git, SVN, самописная система контроля версий. Не многие знают, что Git - это фреймворк, на самом деле, для разработки систем контроля версий. Он проектировался, как фреймворк. Но получился такой классный, что оформился в продукт.

Техписатели посмотрели (и сказали): “А мы тоже хотим версии, нормальное версионирование, а не вот эти названия файликов в Ворде - до ревью, после ревью, версия два-ноль, прочитанное Василием Иванычем…” И на пятой итерации ты просто сходишь с ума. Но мы же не хотим сходить с ума. Мы хотим заниматься осмысленной, творческой, на самом деле, деятельностью. Мы не хотим быть секретарями, которые представлены к Вордовским файлам. Поэтому прекрасно понимаю эту боль с этим Шарепоинтом (SharePoint), на котором куча файлов. И ты просто не хочешь его открывать в какой-то момент. Просто даже не хочешь его открывать.

И вот техписатели посмотрели на это: “А почему бы нам тоже систему контроля версий не иметь?” А в чём плюсы систем контроля версий? В любой момент любой срез ты получаешь. Ещё в любой момент ты получаешь информацию о том, кто и в какой момент вот эту конкретную фразу написал. Там есть такая команда blame (git blame) - ты можешь вплоть до одной буквы получить эту информацию. Тоже бывает полезно в работе с документами. Не говоря уж о дифах (git diff), которые встроены в систему. Не те дифы, которые встроены в Ворде и выглядят, как сравнение документов. Там (в Git) встроены в сам процесс. Техписатели увидели это и подумали, что (для них) это тоже может быть хорошо. Но, мне кажется, что самое важное было не в этом. Мы с тобой говорили про Ворд, про Конфлюенс поговорили.

Давай я сейчас такую картинку попытаюсь нарисовать в головах, чтобы запомнилось. Представим какую-то компанию, в которой сначала был Ворд с Шерапоинтом, каким-то общим диском с файлами; и все по почте общаются, пересылают друг другу (файлы). Потом та история, которую ты мне рассказал, мне очень понравилась - эволюционировали до Конфлюенса, когда поняли что нам нужны комментарии к документам, работа над черновиком. Какие у вас ещё были причины?

Владимир Юсупов: Уменьшить потоки по почте пересылки файлов - одна из причин, а также версионность.

Арина Балерина: Да, версионирование. И может вот ещё… Ты только написал, а оно уже опубликовано в интернете. Не в публичном интернете, но кому-то можно уже послать, при этом не одному человеку. Кто-то сразу может видеть результат и как-то ревьюить его. Это вторая ступень эволюции.

Не хочется сейчас называть третью ступень потому, что параллельные процессы. Кому-то Конфльюенс нужен больше, чем docs-as-code. Тут надо смотреть на ситуацию. Нельзя сказать, что docs-as-code лучше, чем Конфльюенс. Даже нельзя сказать, что docs-as-code лучше, чем Ворд. Однозначного решения нет. Надо смотреть какие инструменты решают задачу и какие задачи стоят перед людьми. Поэтому я сейчас про эволюцию говорю очень условно. Представим, что люди перешли на Конфлюенс, а потом выяснилось, что документация всё равно отстаёт от разработки. Выпускают-выпускают частые релизы и каждый раз документация не успевает. Ещё требуется задерживать релиз на пять дней только ради того, чтобы Семён Анатолич дописал документацию - это же преступление перед коммерческим директором. Есть такое у всех, не только у разработчиков ПО.

Представь, что в этой компании, про которую я сейчас рассказываю, ещё и программисты пишут документацию. Не в смысле, что технический писатель пишет и всё, больше никого туда не пускают. А может быть там технического писателя вообще даже нет; всё писали программисты. Вот они во внутреннюю базу знаний в Конфлюенсе накидывали-накидывали, и выяснилось, что всё равно не успевают, враньё периодически. Проблемы возникают. И вот какому-то программисту в один момент приходит в голову: “Положу я рядом с кодом readme.” Слушай, я так немножко от инженеров отошла, поэтому постоянно переспрашиваю, забыв про то, что у меня курс по C++ был, между прочим, как у инженера.

Итак, кому-то из программистов пришло в голову положить рядом с кодом readme и писать туда сразу. Вот он что-то напрограммировал и, чтобы не забыть, как это работает, сразу в readme пишет маркдауном (Markdown). Маркдаун уже к тому момент изобрели. Им удобно же пользоваться. В смысле, удобно смотреть на этот файл размеченный. Этот программист положил рядом readme и выяснилось, что вот документация в тот же день. Ему (программисту) её удобно обновлять. А вот в Конфлюенс надо мозг свой отдельно выделить, чтобы зайти в этот Конфлюенс, вспомнить, куда это надо написать. Это же задержка на обработку этой операции в мозгу конкретного человека. И классно же, выяснилось, что readme лежит там же в репозитории, где идёт работа над кодом, то как-то быстрее документация делается. Осталось только немножко добавить структуры. Ведь у каждого свой readme и чтобы как-то они пересекались, и сборку добавить, чтобы из этих readme собирались уже документы в нужных форматах, может быть, на сайт это всё генерировалось.

И тогда приходит человек, который называется сейчас DocOps - это специалист по автоматизации в области документационных задач, и говорит: “А я вам сейчас… У нас CI/CD то уже есть для публикации конечного продукта? Давайте ничего нового не будем придумывать. Давайте я вам сейчас систему сборки документации туда же запихну. Просто вместе с продуктом будет пересобираться, тестов на него навесим. Мы знаем, как (это делать). Скрипты уже все есть.” Понимаешь, в итоге рождается docs-as-code. Почему я рассказала эту историю? Важно, что всё-таки инструменты подбираются под задачу. Вот есть у вас в компании Git, вы посмотрите внимательно, нужно вам туда или нет. Может быть, нужно, может быть, нет. Есть у вас система сборки какая-то, посмотрите туда, может вам переиспользовать её. Это будет эффективно, с экономической точки зрения. Да, мы знаем принципы docs-as-code, о них можно почитать, что к документации относятся так же, как к коду, с точки зрения процессов, где мы храним. Системы контроля версий, сразу все называют.

Также все называют IDE. Кстати, это не совсем правильно, потому что docs-as-code - это обязательно писать в IDE вместе с разработчиками. Я хочу предостеречь тут слушателей. Нет, не нужно писать там, прямо обязательно. IDE создан для того, чтобы разрабатывать программные продукты, а не для того, чтобы писать тексты. Если вам неудобно в ней работать - не нужно. Это никак не улучшит ваш опыт. Используйте специализированные инструменты. Достаточно много таких инструментов, которые созданы специально для техписателей и позволяют при этом хранить исходники в Git. Ваш текст, размеченный в маркдауне. Храните в Git, но при этом используйте профильный для вас инструмент, а не заимствованный у разработчиков. Не надо сразу всё заимствовать у разработчиков. Нет, подумайте.

Наверное, так. Скажи мне, пожалуйста, появилась ли какая-то картина законченная?

Заканчивая ответ на твой вопрос, ещё раз скажу - нет однозначного критерия. Я бы знаешь, как разбиралась - есть docs-as-code или нет?

Я бы пошла к человеку, который это внедрял и просто с ним поговорила. Ели бы он мне рассказал картину примерно такую же, которую я вам сейчас описала, то, наверное, да, я бы сказала: “Да, у вас docs-as-code.”

Владимир Юсупов: Да, Арина, спасибо. Понятное объяснение. Сейчас встало больше на свои места. Я читал конечно до этого про концепцию. Ты сейчас так доступно объяснила. Спасибо тебе.

Мы поговорили про концепцию и процесс. Вот теперь мне знаешь интересно что? Мы уже выяснили, что есть такая замечательная профессия - технический писатель. Это тот самый специалист, который пишет техническую документацию и оказывает инженерам неоценимую помощь, чтобы мы, инженеры, больше времени уделяли своим основным задачам и не отвлекались на подготовку документации. К сожалению (или к счастью) для инженеров, технические писатели до сих пор достаточно редкие специалисты в российских компаниях, могу сказать за те, в которых я работал, где работают мои друзья. Мне кажется, в целом на территории СНГ не так развита профессия по тем причинам, которые мы с тобой вначале обсудили, в отличии от США и стран Европы. К тому же я твёрдо убежден, что инженеры в состоянии написать документацию самостоятельно.

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

Арина, по твоему мнению, могут ли не техписатели - инженеры, аналитики - создавать хорошую документацию самостоятельно?

Арина Балерина: Хороший очень вопрос. Я отвечу, но если можно, вспомни аргументы тех людей, которые считают, что (инженеры) не могут (написать хорошую документацию).

Владимир Юсупов: Допустим, касательно инженеров. Я могу их (условно) разделить на несколько групп.

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

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

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

И четвёртая группа - это те инженеры, которые могут (написать документацию). Четвёртая группа - это совсем такой малый сегмент или сектор в круговой диаграмме.

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

Вкратце если (описать ситуацию).

Арина Балерина: Вкратце можно подраться, а документация так и не будет создана. Потому что все заняты тем, что выясняют, кто круче.

Я сейчас буду перебежчиком. Буду перебегать то на сторону одних, то на сторону других. Попытайтесь следить за моими перемещениями.

Так, для начала, я сейчас специализируюсь на публичной документации для разработчиков. Это документация, у которой конечный пользователь - это программист. Не человек, который пользуется конечным продуктом, кнопки нажимает, а именно программист. Я документирую API. Не прямо вот сейчас, а специализируюсь на этом. Здесь я встану на позицию твоих оппонентов, присоединюсь к ним. Делать публичную документацию довольно сложно. Мы должны знать много. Да просто знать русский язык. Мы должны много знать про его современные тенденции. Например, как мы пишем “вы” с большой буквы или с маленькой. Это же ещё надо обосновать перед руководством. Мы должны знать предметную область.

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

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

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

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

Кажется, что это может сделать любой. Но нет. Крутые тексты пишут крутые профессионалы.

Владимир Юсупов: Я понял тебя и согласен с тобой.

Кстати, твоя формулировка, твоё объяснение и твои аргументы оказали более весомое влияние на меня сейчас. Я соглашусь с тобой, что, как минимум, написанием публичной документации инженеру лучше не заниматься. Тут этим делом должен профессионал (техписатель). Согласен с тобой.

Арина, мы поговорили сейчас про написание хорошей документации как инженерами, таки техписателями. Все говорят: “Качественная документация, хорошая документация”. Она должна быть определённым образом оформлена, так то написана. Всё-таки что же такое вообще качественная документация в твоем понимании?

Арина Балерина: Володя, очень хороший вопрос. Это один из тех вопросов, на который можно одновременно просто и честно ответить и в то же время не смочь ответить.

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

Мы понимаем, что “хорошо решает ту задачу, для которой она создавалась” это что имеется в виду? Документация должна быть полной, непротиворечивой, в полной мере помогать пользователю, а не мешать ему. Тогда мы можем выписать себе, какие свойства у неё должны быть.

Допустим, красивое оформление не для эстетического удовольствия. Хотя и это тоже. В целом оформление работает на передачу смыслов. И мы можем всё это выписать…

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

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

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

Я здесь что хочу сказать. Когда мы предыдущую тему обсуждали, ты сказал, что технические писатели редкие специалисты в компании.

Владимир Юсупов: Я бы сказал, что не такие частые в штате. По крайней мере, в тех, в которых я работал, и в целом по отраслям.

Арина Балерина: А у тебя есть гипотеза, почему это так?

Владимир Юсупов: Я могу сказать лишь за свою сферу. Я пятнадцать лет почти работаю в IT. Практически весь мой опыт построен вокруг конкретного программного обеспечения - SAP. Специалистов, которые работают с SAP-ом, называют SAP-консультанты.

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

За остальные сферы не могу сказать, не знаю. Как предположение - кто-то из инженеров делает эту работу.

Арина Балерина: Как говорила Фаина Раневская… По крайней мере, ей приписывают. Можно?

Владимир Юсупов: Да, я понял, про что ты хочешь сказать.

Арина Балерина: Ладно, я не буду произносить… Есть, а слова нет… Сначала думала произнести, но поняла, что я - не Фаина Раневская. Может быть не надо…

Владимир Юсупов: Да, у меня просто 0+ (контент подкаста), поэтому не надо, забанят.

Арина Балерина: Понятно, хорошо.

Мне нравится твоя гипотеза. Давай честно - на документации экономят. Почему они (техписатели) редкие, объяснение простое - на документации экономят. Дальше можно посмотреть вглубь и попытаться понять, а почему же экономят. Может быть, это и неплохо? Может быть, это хорошо.

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

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

Не могу подобрать эквивалент… Есть такое понятие “Time to Market”. Я начинала с IT-консалтинга в Корус консалтинге. Я прекрасно помню этот момент, когда в двенадцать часов ночи бухгалтер энтерпрайза позвонил, а в три часа утра у него уже всё исправили. Там речь идёт о больших деньгах. Зачем там технический писатель в этот момент? Аналитик невыспавшийся всё сделал и хорошо.

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

Ещё я бы не стала экономить на внутренней документации. Если компания большая, много транзакций в разные стороны. И если все будут дёргать этого несчастного архитектора целый день и спрашивать одно и то же, это же ужас будет. Или же наоборот, растущая компания, где есть проблема онбординга. Нанимаем много-много молодых специалистов. Их всех одновременно пятнадцать человек собрали и нужно всех погружать. И погружать надо быстро, чтобы они какую-то прибыль уже приносили через два месяца, а не через полгода. Тогда нам нужна хорошая внутрення документация, чтобы они (молодые специалисты) не бегали к архитектору и дёргали его, а он их ненавидел. Потому что детский сад. Здесь сталкиваются две экономии. С одной стороны, надо экономить деньги. Я всегда за экономию денег, я за коммерческое обоснование всего. С другой стороны, надо смотреть, как нам сэкономить мозг дорогих специалистов. И если мы хотим сэкономить мозг, я по-другому это назвать не могу… Если архитектор, который разрабатывает систему, отвлекается на пятнадцать минут сюда, на пятнадцать минут туда и на пятнадцать минут ещё куда-то, он ничего не делает за день, во-первых, а во-вторых, он через полгода выгорит и уволится. Вы ещё на найме потеряете денег.

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

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

Владимир Юсупов: Не в рамках (всей) компании конечно, а в рамках конкретного направления.

Арина Балерина: Да, в рамках направления.

Владимир Юсупов: Я понял тебя, Арина.

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

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

Арина Балерина: Спасибо. Приятный очень вопрос.

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

Я сейчас добавлю, что я периодически работала, как редактор, который помогает компаниям писать технические тексты публичные на Хабр, например. Как это происходит. Я не знаю эту тему, о которой они пишут, собираются написать. У них есть сотрудник, который эту тему знает. У него есть знания и какая-то концепция, о чём он хочет рассказать. Но приглашают редактора…

Чтобы было сразу понятно, редактор - это не тот человек, который будет запятые править. Это корректор. Редактор, в моём случае - это человек, который больше, как журналист работает, то есть помогает создать статью человеку, который не занимается этим профессионально.

Владимир Юсупов: Некий архитектор получается (в части) написания статьи. Правильно или не совсем?

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

Возвращаясь к теме “не любят”. К чему я это рассказываю? Мой опыт показывает, что навык писать тексты, хорошо писать, навык хорошо говорить и навык знать, разбираться в предметной области - это вообще разные вещи.

Нельзя считать, что если человек хорошо разбирается в предмете, он также хорошо сможет написать о нём. Также нельзя считать, что если человек хорошо говорит о чём-то, рассказывает, то он сможет написать. И наоборот. Согласен?

Кто-то классно пишет, а разговаривать ему тяжело, например. Таким людям нужно сесть, как-то план написать в тишине.

Владимир Юсупов: Я такой. Мне надо посидеть, подумать, пописать. У меня с ораторскими качествами не очень (хорошо), но писать я люблю.

Арина Балерина: Ты преуменьшаешь, мне нравится с тобой сейчас беседовать.

Владимир Юсупов: Спасибо, я долго готовился.

Арина Балерина: Я тоже готовилась. Хотя у нас с тобой беседа просто. Мы импровизируем. Я слушателям говорю, что мы не репетировали.

Так вот, люди не любят… Я сейчас хочу порекомендовать те книги, которые позволят полюбить. Не в смысле, вас кто-то заставил писать и вам нужно быстренько сделать, написать. Это ChatGPT пусть пишет, если честно. Не надо себя нагружать этим. Или на аутсорс отдайте. Я хочу помочь полюбить писать.

Бывает так, что люди не пишут потому, что их в школе заставили разлюбить это делать. Почему кто-то может не любить? Например, кому-то нужно погрузиться в лучшие практики сначала, чтобы не блуждать там в потёмках, а сразу прочить про то, как принято, и тогда сразу быстро и хорошо написать. Мы сейчас про документацию говорим. В этом смысле я рекомендую книгу Юрия Кагарлицкого. Забыла её название и не записала себе. Но это о том, как писать техническую документацию. Точное название не скажу.

Владимир Юсупов: Мы ссылки добавим в описание.

Арина Балерина: Да, добавим. Книга Юрия Кагарлицкого о том, как писать техническую документацию. Там он учит системному подходу вплоть до того, чтобы ограничиться девятью разделами вместо двенадцати в каких-то ситуациях. Вторая книга, которую я рекомендую для того, чтобы полюбить писать - Максим Ильяхов. Знаком?

Владимир Юсупов: Да, знаком. Я не читал её (эту книгу), но на слуху.

Арина Балерина: Не читал, но осуждаю. Многие, кстати, не читали Ильяхова, но он настолько на слуху, что люди готовы осуждать его, даже не читая. Максим Ильяхов написал “Пиши и сокращай”. Вторая книга вышла, переработанная. Максим Ильяхов и, кстати, Людмила Сарычева. Про Людмилу Сарычев все забывают, прекрасный редактор.

Владимир Юсупов: В соавторстве?

Арина Балерина: Они в соавторстве написали, да. Почему я их рекомендую? Бывает, что вам мешает канцелярит. Канцелярит - это такое… “Ит” - это вообще значит воспаление. Дифтерит.

Владимир Юсупов: Корней Чуковский.

Арина Балерина: Да-да. Он, кстати, к языку приложил (руку) тоже. Это же его слово!

Владимир Юсупов: Это его слово, да. Живой… Как же называется книга…

Арина Балерина: “Живой и мёртвый” - это Нора Галь. Кстати, я её тоже рекомендую.

Владимир Юсупов: Нет, не “Живой и мёртвый”, а “Живой” про русский язык он написал. Живой… Забыл. Корней Чуковский. Можно его тоже добавить (в список). Мне нравится эта книга. Извини, перебил тебя.

Арина Балерина: Обязательно. Спасибо тебе. Можно заменить Максима Ильяхова на Нору Галь и Корнея Чуковского, если ближе. К чему я это всё?

Эти книги не научат вас писать. Они дадут вам разрешение не использовать канцелярит. И если вам понравится… Бывают люди, которые читают эти книги и потом говорят: “А что так можно было? Мне казалось мне нужно какую-то сложную формулировку придумать.” На самом деле, есть разрешение от авторов книг писать просто и понятно.

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

Можно, во-первых, спрашивать: “Посоветуйте книгу. У меня такая вот проблема.” Вам ещё три часа будут советовать книги. Ещё можно, перед тем, как задать вопрос, поискать по тегу #знания. Его запоминать не нужно, в закрепе чата есть список тегов. По этому тегу поискать и посмотреть, что рекомендуют техписателям. У нас есть тег #текст, который про вопросы, связанные непосредственно с текстом, не с предметной областью, а прямо как сформулировать.

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

Владимир Юсупов: Ёлочки, лапки.

Арина Балерина: Вот, да. Использование тире. То есть всё, что относится к области типографики. Это я к чему?

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

Я как техписатель, если бы сейчас пришла в какую-то новую компанию, первое, что я бы сделала, я бы начала с составление глоссария, чтобы по ходу его составления разбираться в предметной области. Если его (глоссария) нет до моего прихода. Второе, что бы я сделала - я бы составила, так называемы, стайл гайд (style guide) или гид по стилю. Это такой документ, в котором написано, как мы пишем те или иные слова, как правильно их писать. Много-много терминов, которые все пишут по-разному. Например, бэкэнд - бекенд. Чтобы люди на это время не тратили, а могли просто пойти и проверить. И я могла бы их автоматом проверять, автоматические проверки настроить, чтобы в документах вылавливать ошибки.

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

Владимир Юсупов: Да, понятно.

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

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

Владимир Юсупов: Кстати, ты сейчас сказала читать тех людей, которые нравятся. Была такая фраза. Не помню её дословно, но суть следующая - если нравится какой-то писатель, то читайте того, кого читает он.

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

Арина Балерина: Хорошо. Давай попробуем.

Владимир Юсупов: Готова?

Арина Балерина: Да.

Владимир Юсупов: Хорошо. Итак, вопросы.

Текст или код?

Арина Балерина: Убил… Как в морском бое. Я не знаю… Текст.

Владимир Юсупов: Руководитель или исполнитель?

Арина Балерина: Я уже… руководитель…

Владимир Юсупов: Быстро или качественно?

Арина Балерина: Быстро.

Владимир Юсупов: Сегодня или завтра?

Арина Балерина: Завтра конечно. Я же нормальный человек.

Владимир Юсупов: И последний. Одиночка или команда?

Арина Балерина: Да что же такое… Такая дихотомия… Ладно, одиночка.

Владимир Юсупов: Молодец! Прекрасные ответы. Правильных ответов у меня нет.

Арина Балерина: У тебя есть типизация какая-то?

Владимир Юсупов: В принципе, я ожидал, что ты так ответишь. Я тебе потом расскажу, за кадром.

Арина Балерина: Хорошо, договорились. Спасибо. Это было весело.

Владимир Юсупов: Арина, вообще был замечательный разговор. Признаюсь, у меня давно не было такого интересного собеседника. Честно тебе говорю.

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

Арина Балерина: Да, я иногда шучу, что, если мы будем стоять с вами в очереди за картошкой и у вас будут какие-то проблемы с документацией, то вы выйдете из очереди не только с картошкой, но и с планом по развитию. Поэтому я люблю очень отвечать на вопросы. Это развивает меня, в том числе. Поэтому ко мне можно обратиться через…

Давай так, если это прямо запрос на менторство, то через гетментор (getmentor.dev). Ссылка будет в описании. Первый разговор бесплатный. Мы можем просто поговорить о проблеме. Возможно, это уже будет решение.

Второй канал - я целыми днями сижу в чате техписателей. Меня там легко найти по нику “Арина Балерина”. Можете прямо тегать, если хотите. Или можно задавать вопросы, если я онлайн и если понятный мне вопрос, я могу ответить, я отвечаю.

Владимир Юсупов: Понятно. Спасибо. Все ссылки мы добавим в описание.

Арина, благодарю тебя, что ты согласилась побеседовать и поделилась интересной информацией со мной и слушателями подкаста технического коммуникатора!

На носу уже Новый год. Поздравляю тебя с Наступающим Новым годом! Искренне желаю тебе успехов! Всего тебе доброго! Спасибо тебе большое!

Арина Балерина: Володя, спасибо тебе большое за эту возможность и за то, какой ты собеседник. Мне было очень приятно с тобой разговаривать. И твой подкаст мне нравится. У нас оказалось столько общих тем, не смотря на то, что я давно уже не в индустрии.

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

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

Владимир Юсупов: Согласен. Взаимно. Спасибо большое, Арина.

Арина Балерина: Спасибо всем слушателям. Не прощаемся.

Владимир Юсупов: Пока, Арина.

Арина Балерина: Пока-пока.

Владимир Юсупов: Спасибо, что прослушали этот выпуск от начала до конца. Если у Вас возникли вопросы, замечания или предложения ко мне или Арине, пишите нам. Мои контакты вы можете найти на моем сайте techwritex.ru. Контакты Арины добавлены к описанию данного выпуска. И конечно же подписывайтесь на подкаст.

Пользуясь случаем, поздравляю вас с Новым годом и желаю успехов в Новом году!

На этом у меня всё.

До встречи!

С Вами был Владимир Юсупов. Подкаст технического коммуникатора Техкомпод. Пока!