Выпуск #20. Беседа с Константином Макушевым

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

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

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

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

Контакты Константина Макушева:

Профиль в социальной сети

Публикации на Хабре

Книги, которые рекомендует Константин:

• Нора Галь «Живое и мёртвое»
• Максим Ильяхов «Пиши и сокращай»
• Уильям Зинсер «Как писать хорошо»

Другие рекомендации Константина:

Телеграм-канал сообщества русскоязычных технических писателей

Write the Docs – глобальное сообщество людей, которым небезразлична документация (только на английском языке).

Mermaid Diagram - инструмент для создания диаграмм и визуализации с помощью кода.

Diataxis - систематический подход к созданию технической документации.

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

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

---

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

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

С вами Владимир Юсупов - технический коммуникатор и ведущий данного подкаста.

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

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

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

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

Итак, запись беседы с Константином Макушевым.

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

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

Константин Макушев: Привет!

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

Константин Макушев: Ты меня заинтриговал.

Владимир Юсупов: Поясню для слушателей, что в профиле было написано следующее: Инженер, который любит писать. В переводе на русский. Ну, или в оригинале: An engineer who likes writing. Сейчас ты работаешь техническим писателем, но это не единственная позиция в твоём интересном, скажем так, послужном списке. Расскажи, пожалуйста, о своём профессиональном опыте, как ты стал техническим писателем, с чего всё начиналось.

Константин Макушев: Ну, всё верно. Я скажу так, что я идентифицирую себя как инженер именно, хотя технический писатель это достаточно разнообразная профессия и среди технических писателей много людей, которые пришли, например, из лингвистики, то есть из языковой школы, скажем так. Но я пришёл из физической школы. Я заканчивал Алтайский Физтех по направлению Радиофизика. И вот как я пришёл к техническому писательству, если заходить издалека, ну, скажем, заходить с университета, то в университете мне как-то всегда нравилось больше объяснять людям что-то и описывать, как что-то работает, чем считать цифры. Хотя цифры считать тоже, конечно, это интересное занятие, но для меня почему-то как-то более интересным, волнительным было именно рассказывать о результатах расчётов, показывать графики, писать статьи научные, вот это всё. Я после университета остался в аспирантуре и достаточно долгое время научной деятельностью занимался как младший научный сотрудник. И как-то раз научный руководитель попросил меня в 12 часов ночи срочно перевести пару страничек на английский для заявки на грант. То есть мы писали заявку на грант, и она должна была быть на русском и на английском. Чтобы эксперты англоязычные, международные могли её тоже понять. И, соответственно, на кафедре разделили эти задачи, то есть по страничке вот в режиме цейтнот, так скажем, решили перевести всё это быстренько. И мне досталась пара страничек, и я с большим удовольствием их перевел на английский. И так неплохо получилось, что руководитель меня на утро очень похвалил, сказал: «Ничего себе, ты молодец! Я не ожидал от тебя такого.» И я подумал, что здорово же. И, возможно, мне стоит этим заняться более профессионально, углубленно. И тогда я решил поискать возможности в переводе. То есть поискать работу технического переводчика. Стал в целом изучать, что за профессия, как она выглядит, искать какие-то фриланс-возможности. Ушло у меня на это где-то полгода, наверное. У меня был какой-то маленький заказ. Было несколько неудачных попыток войти в эту профессию. Но в итоге мне написали ребята из одной компании, сказали, что вот им нужен перевод какой-то инструкции к насосам в короткий срок. Для меня хорошим сигналом послужило, что они оплатили тестовое задание. То есть, как бы, настроены серьезно были. Я выполнил им тестовое задание. И они сказали: «Окей, давай работать». Я поработал. Они мне оплатили первый заказ, потом второй заказ. Потом я спросил, как бы, может быть, больше заказов получить. И в итоге мне предложили постоянную работу удаленно техническим переводчиком. У меня как раз так всё сложилось, что к тому времени у меня в университете научная деятельность пошла на спад по разным причинам. И так вот я в итоге постепенно из научной академической среды перешёл как бы в переводчики. Я там какое-то время оставался работать в университете, как раз моими навыками активно пользовались для написание статей для переводов и так далее. То есть мы писали статьи, продолжали писать на английском. Но основной деятельностью моей стал технический перевод. Набравшись опыта в техническом переводе, довольно много времени я так работал, примерно около пяти лет, если я не ошибаюсь. Я получил большую насмотренность на техническую документацию. Хорошее понимание и языковые компетенции прокачал неплохо, и хорошее понимание того, как выглядит хорошая документация и как она формулируется, из чего она состоит. В итоге я подумал, что пора бы как-то двинуться дальше и попробовать себя в техническом писательстве. И, прочитав, может быть, одну книжку, я решил, что всё, я готов. И стал подавать, то есть рассылать резюме на технического писателя. Довольно быстро, со второго раза примерно, у меня получилось найти Наверное, одну из лучших работ в моей жизни, в одном из лучших мест, в одной из лучших компаний для технических писателей, в documentat. Меня взяли после тестового испытания небольшого и собеседований. И вот так я стал техническим писателем.

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

Константин Макушев: Работа технического писателя на самом деле, вопреки названию, состоит процентов на 70, как минимум, не из того, чтобы писать, скажем так. Это абсолютно другие активности. Во-первых, технический писатель — это человек, который исследует продукт, который он описывает, общается с разработчиками, общается с другими людьми, общается с другими техническими писателями, общается с аналитиками и так далее. Для чего он это делает? Для того, чтобы представить у себя в голове те сценарии, которыми пользователь использует продукт. То есть сценарий использования продукта – что нужно пользователю, для чего он использует продукты и для чего он открывает документацию. Чтобы написать какую-то инструкцию, нужно очень хорошо понимать, как пользователь будет по этой инструкции двигаться. Нужно брать, грубо говоря, продукт и тестировать его, и проверять, что действительно то, что ты собираешься написать, что оно работает. Поэтому работа техписа, как правило, она процентов на 70 состоит из вот этих активностей, из тестирования, но не такого тестирования, как тестировщики тестируют. Здесь важно понимать отличия. Тестировщик тестирует программу, например, чтобы найти в ней какие-то проблемы. Он специально создает какие-то условия, чтобы программу сломать. Пытается ее сломать. А технический писатель не пытается сломать, он пытается просто пройти так, как задумывалось изначально пройти. Пройти тот или иной сценарий пользовательский. И вот это большая часть работы на самом деле. То есть это анализ, тестирование, исследования, коммуникация и так далее. В этом смысле работа техписателя очень похожа на работу учёного, то есть, академического сотрудника, потому что учёный же тоже пишет в итоге статью. Основным показателем работы учёного является опубликованная научная статья. Но это абсолютно не значит, что учёный большую часть времени пишет эту статью. Большую часть времени учёный исследует предмет, проводит какие-то испытания и так далее, ставить эксперименты, расчёты и прочее. И по итогам этих экспериментов и исследований он пишет статью. И технический писатель, в принципе, делает то же самое. Только, может быть, исследование его не настолько фундаментальное. Но образ работы примерно такой же. Поэтому, на самом деле, мне вот мой опыт в академической деятельности очень помог и помогает до сих пор в работе техписателя, потому что эти подходы к анализу, к решению проблем и так далее, похожи.

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

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

Владимир Юсупов: Костя, если вот, так сказать, мы по базам прошлись, по пониманию профессии, то предлагаю перейти немножко к таким более прикладным вещам. Как ранее я тебе уже сказал о нашей второй виртуальной встрече. Первая, на самом деле, состоялась при следующих обстоятельствах. В одном из подразделений компании, где я сейчас работаю, с недавнего времени мы пересмотрели подход к ведению документации, её организации, хранению. В принципе, не так давно я узнал про один из таких подходов. Он же, как в моём понимании, является неким фреймворком. Я говорю о Diataxis, который был сформулирован Даниэлем Просида. Я послушал и посмотрел несколько выступлений и вебинаров на эту тему, а потом мне стало интересно, есть ли какая-то информация о применении Diataxis русскоговорящими специалистами. И поисковик мне сразу же выдал в результате твою статью на Хабре. Вот так я впервые с тобой познакомился. Ты достаточно хорошо разобрался в Diataxis. И расскажи, пожалуйста, слушателям об основной идее этого подхода в плане организации документации. И есть ли у тебя опыт применения Diataxis на практике?

Константин Макушев: Да. Это статья, которую мы написали совместно Семёном Факторовичем. Это не то чтобы моя единоличная статья. Действительно, Diataxis — это достаточно эффективный подход к организации документации. Идея его заключается в том, чтобы чётко разделить документацию по жанрам и писать её в разных разделах для соответствующего жанра. И жанры следующие — это концепции, где мы рассказываем пользователю, что у системы под капотом находится. Они ориентированы на пользователей, которым интересно знать, как работает система, которые хотят понять лучше для себя, что происходит, но при этом концепции не дают никаких указаний к действию, это просто как бы вот такая, можно сказать, энциклопедия, что ли, или книжка, или учебник. Скорее всего, учебник более правильно будет здесь. То есть учебник, который объясняет, как что-то работает, как что-то устроено. Второй жанр – это туториалы, где мы обучаем пользователя, как использовать нашу систему. То есть когда пользователь совсем новый, систему ещё не трогал, не знает, как она работает, не знает, куда нажать вообще, то есть, где какие кнопки. Мы в туториале даём ему конкретный пример какой-то, как написать Hello World, например, на Python. Вот мы ему говорим: “Открой IDE, напиши, запусти вот так вот компиляцию и так далее”. Вот это пример туториала, когда мы пользователя за ручку проводим по каким-то основным возможностям нашей системы. Третий жанр — это инструкции, то есть how-to-guides в оригинале называется. Это какие-то пошаговые инструкции о том, как пользователю решить какую-то рабочую задачу. Здесь мы уже не вводим пользователя за ручку, а предполагаем, что пользователь пришёл с каким-то вопросом конкретным по своей работе, например, как ему…

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

Константин Макушев: Да, конкретная рабочая задача, как загрузить данные в хранилище. Спасибо за пример. Как загрузить данные в хранилище. И мы конкретно даём ему шаги, которые нужно выполнить, как загрузить данные в хранилище. Но мы не даём ему данные, мы не создаем с ним хранилище. Мы предполагаем, что у него всё уже есть. У него есть данные, у него есть хранилище. Ему надо их загрузить. Отличие от туториала в том, что в туториале, если бы мы писали на ту же тему, то мы бы создали с пользователем файлик данными, показали бы ему, куда нажать, чтобы создать хранилище, и итогом нашего туториала стали бы данные конкретные, которые мы дали пользователю в конкретном хранилище, которое мы с ним создали. То есть мы провели за ручку его. Здесь в гайдах, то есть в инструкциях мы уже не проводим пользователя за ручку. Мы просто объясняем ему, что нужно сделать, предполагая, что это уже какой-то взрослый пользователь, который уже какие-то рабочие свои задачи решает. Ну и последний, четвертый жанр — это справочники (в записи оговорка про инструкции), где мы перечисляем какие-то функции системы, какие-то ее возможности. Например, API методов или список параметров, которые можно передать в командной строке, или список чего бы то ни было ещё, что есть в системе и что требует просто описания каждого элемента в отдельности, то есть как справочник. И мы предполагаем, что пользователь не будет читать этот справочник от корки до корки, а будет приходить в справочник, чтобы по конкретному элементу, который ему нужен в данный момент в работе, посмотреть, что этот элемент делает, как он работает. Вот такие четыре жанра. В чём фишка и почему это работает? Это работает, потому что это отвечает тому сценарию, с которым пользователь открывает документацию. Пользователь же не открывает документацию, чтобы просто прочитать ее от корки до корки обычно. Он её открывает с какой-то целью. Он либо начал пользоваться и хочет понять, как что-то сделать, либо он начал пользоваться, он вообще ничего не понимает, ему надо понять, откуда стартовать, либо ему интересно действительно почитать, что под капотом происходит у системы в этот момент, либо ему нужно что-то конкретное, например, по конкретной функции узнать, что эта функция делает. И вот эти четыре сценария основных, которыми пользователь открывает документацию, они как раз и ложатся на вот эту систему. Честно говоря, я сейчас пересказываю тебе статью. Вопрос твой был в том, насколько я помню, как мы используем на практике это дело.

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

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

Владимир Юсупов: Да, спасибо тебе за разъяснение. Мы тоже на работе сейчас перелопачиваем всю документацию, которая у нас имеется – эти тысячи Excel, Word, PDF, Visio файлов – пытаемся свести сейчас на портале. И как раз у меня тоже приглянулся этот подход, тоже пытаемся его как-то применить у себя. И то, что ты сказал, правда, мы как раз концепции больше используем и, наверное, у нас хаутушки ещё хорошо идут. Справочники мы тоже не использовали.

Константин Макушев: Ну да, да. То есть вот концепции и пошаговые, они практически в любой системе.

Владимир Юсупов: Да, хорошо. По Diataxis вообще очень интересно. Ну, кстати, в описании выпуска я дам ссылку на статью о Diataxis. Причём там, что очень мне понравилось, наглядная табличка с четырьмя этими квадрантами. Рекомендую посмотреть.

Константин Макушев: Там же, кстати, можно найти примеры техдокументаций, которые сделаны по Diataxis успешно достаточно.

Владимир Юсупов: Костя, ты ранее рассказывал, что ты достаточно продолжительное время занимался техническим переводом с английского языка. И, если не возражаешь, я хотел немного сейчас на этом моменте остановиться. Как ты знаешь, в начале года Семён Факторович проводил этот большой опрос о технической документации, о тех, кто её разрабатывает. И наверняка ты тоже в нем участвовал. Там был один интересный вопрос такой, который, кстати, мы обсуждали в беседе с Иваном Чаплыгиным о переводе документации. Так вот, там был один из вопросов. Дословно сейчас не помню, но смысл следующий: если вы пишете документацию на английском, вы пишете ее на английском сразу или используете, ну, скажем так, промежуточную версию русского, то есть с одного русского на второй русский, а потом уже со второго русского на английский? Вот на твоём опыте какой все-таки вариант перевода чаще встречается или как у тебя это работает? Ты сразу на английский или вот как-то с разработчиком связываешься, выясняешь какие-то нюансы, а потом уже на английский? Константин Макушев: Ну, в последнее время я редко пишу документацию на английском, честно говоря. Но когда мне приходилось писать, то у меня в основном была двуязычная история, когда надо было писать на русском документацию, а потом на английском. То есть было две версии. И тогда я писал сначала на русском, потому что он проще и родной. И когда меня всё на русском устраивало, я садился и делал английскую версию. Но когда у меня был кейс, когда мне надо было писать только на английском, то я писал сразу только на английском, потому что тратить время писать на русском и потом переводить. Для меня это просто трата времени была, хотя я не шеймлю (не пристыжаю, примечание В.Ю.) тех, кто так делает. Для кого-то так, может быть, проще, удобнее сначала всё сформулировать на русском, потом заняться переводом. Но если у вас достаточно уже опыта, скажем, языковых компетенций, вы можете переключиться и начать думать на английском. Это, кстати, полезная практика. Я всем рекомендую иногда так делать, если вы изучаете язык особенно. Просто стараться переключиться и попробовать думать вообще об окружающих вещах на английском, например. Сказать себе внутри по-английски, чем я сейчас занимаюсь. И в таком духе. Это помогает, в общем, формулировать мысли, научиться на английском сразу. И да, в таком случае, когда мне надо только на английском, то я сразу писал на английском, чтобы не тратить время на перевод туда-сюда, потому что всё же сама структура предложений и то, как мы строим фразу, она сильно отличается. Особенно в документации принято, в английской документации приняты некоторые, скажем, формы определённые. И, может быть, они местами плохо с русским языком ложатся, так скажем. То есть не получится дословно перевести в чём суть. То есть то, как ты напишешь на русском, у тебя не получится как-то это слово в слово перевести на английский, чтобы это не выглядело по-русски написанным. И тебе придется всё равно большую работу проводить над формулировкой. И чтобы не делать эту двойную лишнюю работу, если позволяют навыки лучше сразу на английском это делать.

Владимир Юсупов: Если вот продолжить тему перевода документации. Опять же, не каждая компания в России в своём штате имеет техписателей. Я просто знаю, что в моей сфере вообще нигде нет техписателей. Инженеры сами пишут документацию. Да и переводчиков тоже, кстати. Тем не менее, часто возникают задачи, которые ставят разработчикам продукта выполнить технический перевод документации – Ну, вы же айтишники, владеете уровнем выполнения технического перевода, да и не художественное произведение требуется написать. В общем, напишите как-нибудь. Наверняка ты сталкивался с подобными ситуациями в плане того, что можешь ли ты привести примеры каких-то типовых ошибок, которые допускаются инженерами или переводчиками, в принципе, при переводе документации, чтобы, хоть как-то уберечь инженеров условных от граблей, на которые уже неоднократно наступали их коллеги. Например, по твоём опыте.

Константин Макушев: Ну, смотри, у меня не то чтобы много опыта было какого-то ревью документации, которые написали бы русскоязычные инженеры. Хотя есть такой опыт, да, я про это даже написал целую серию статей, всем рекомендую (ознакомиться со статьями, примечание В.Ю.). Знаешь, я вот могу сказать за нерусскоязычных. Я когда переводчиком работал и переводил документацию техническую, которую писали немцы на английском. Я очень чётко научился узнавать их почерк, потому что они напряжение электрическое писали как tension, то есть как физическое напряжение. Потому что у них в немецком, насколько я понимаю, tension – это и физическое, и электрическое напряжение. А в английском это voltage. Но они упорно писали tension. И ты вначале сидишь в какой-то фрустрации, не понимаешь, откуда здесь появился tension вообще, что это такое, особенно когда контекста не очень много, и приходится разбираться, что это за tension такой, чтобы понять, что это просто электрическое напряжение. Я думаю, что русскоязычные, в принципе, техписатели те же самые, скорее всего, такие же ошибки допускают. Вероятно, я в их числе. Что мы используем какие-то выражения, фразы, термины, какие-то ложные друзья переводчика, чтобы изложить мысль на английском в то время, как мы ее излагаем на нашем, на русском. И это порой создаёт, сложности, ухудшает качество документации, скажем так. Вообще, к твоему вопросу, если в целом относиться, то, конечно, это плохая практика, когда инженеров заставляют писать документацию, да ещё и на английском. Я, конечно, сторонник того, чтобы каждый занимался своим делом. И тот, кто любит считать, считал. Для того, чтобы писать и переводить документацию, надо нанять инженера, может быть, который любит этим заниматься.

Владимир Юсупов: Твои слова да в уши кое-кому…

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

Владимир Юсупов: Да, поддерживаю тебя в этом. Кость, вот ты сейчас упомянула, кстати, про статьи об английском на Хабре. И я вспомнил просто, в одной из твоих статей ты рассказываешь про упрощённый технический английский или Simplified Technical English. А вот слышал ли ты или, возможно, применял в работе упрощённый технический русский язык?

Константин Макушев: Я слышал про него, но в работе не употреблял, как-то не было такого запроса, скажем так.

Владимир Юсупов: Да, ты знаешь, я вот как бы ни с тем, ни с другим напрямую не сталкивался, но просто такой вспомнил момент. Просили меня как-то подготовить инструкцию пользователям на упрощённом русском. Вот я честно признаюсь, до того момента, когда мне это сказали, я и не слышал о таком. Начали разбираться и выяснилось, что один из руководителей, который поставил задачу разработки инструкции, Где-то когда-то услышал фразу про упрощённый технически русский язык или УТР. С этого всё и началось. Для меня вообще, в принципе, сочетание слов упрощённый технический русский словно какое-то масло масляное, потому что технический язык, он по своей сути уже является таким, скажем, упрощённым по отношению к тому же литературному языку. Это такие конкретные, какие-то чёткие, понятные формулировки без лишних сложных оборотов. Но потом я так все-таки решил посмотреть за полностью пробел в знаниях, и действительно существует стандарт такой, ГОСТ. Сейчас по памяти не вспомню номер. Называется, по-моему, Перевод эксплуатационной документации на изделие авиационной техники, по-моему, на иностранные языки. И там как раз введено понятие УТР. Как я понимаю, этот ГОСТ является неким аналогом спецификации STE-100 (Simplified Technical English). Если я правильно понимаю, этот ГОСТ используют обычно переводчики, не технические писатели. Они (техписатели) не руководствуются своей работой. Ну, возможно, я ошибаюсь. Если, может быть, кто-то из слушателей работает или сталкивался в своей работе с этим ГОСТом, то, пожалуйста, поделитесь своим опытом. Если у кого-то есть желание, то можно будет отдельно побеседовать, например, на эту тему. И просто когда я прочитал твою статью, я вспомнил этот случай.

Константин Макушев: Ну, это очень интересно на самом деле, потому что я, честно говоря, не сталкивался с ним напрямую. Я подозреваю, что там какие-то более строгие правила, чем просто в нашем понимании упрощённый технический язык. Если это с нашей точки зрения как носители языка, он может казаться достаточно простым. Но, скажем, с точки зрения какого-нибудь иностранца, который откроет этот документ, он покажется уже не таким уж простым, потому что там могут оказаться какие-нибудь синонимы или какие-нибудь просто сложные слова какие-то, которые нам понятны, даже не задумываясь, а иностранцу могут быть сложны для понимания, который, например, учил русский как иностранный. Скорее всего, там какие-то более жесткие правила. Точно так же, как в упрощённом техническом английском. Он весь как бы заточен под международную аудиторию. Причем, под аудиторию, скажем, у которой уровень, ну, может быть, там, A2 или B1.

Владимир Юсупов: Да, кстати, да. Да-да, возможно, ты прав.

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

Владимир Юсупов: Да, я просто посмотрел опять же на это с точки зрения носителя языка, и мне это кажется немного несуразным. Ты сейчас пояснил. Да, все верно. Костя, у меня вопрос ещё такой. Теперь если возвращаясь к ежедневной работе, вопрос по оснастке, то есть по инструментам, которые ты используешь в своей работе. Расскажи, пожалуйста, про стек технологий для написания текста, подготовки изображений, хранения, организации документации и так далее, описания API. Ну, чем вообще ты пользуешься в работе своей?

Константин Макушев: Ну, в своей работе в основном я пользуюсь Docs as Code подходом. То есть когда документация хранится в виде Markdown файлов простых, хранится в репозитории, и собирается, соответственно, каким-то движком в статический сайт. И в итоге пользователь видит документацию на сайте таким образом. Изменения в такую документацию вносятся через механизм MR-ов или PR-ов, в зависимости от того, что у вас GitLab или GitHub. По-разному это называется. То есть запросы на вливание. Какие преимущества это даёт? В основном то, что это даёт возможности отслеживать изменения и проводить ревью этих изменений. Когда, например, чтобы написать документацию, участвует много народу. Например, это может быть технический писатель и множество инженеров. Вот инженеры, допустим, у них что-то поменялось в системе, они понимают, что надо что-то поменять в документации. И для этого они вносят правки в репозиторий, открывают этот MR, как мы его коротко называем. И я вижу, какие правки инженер предложил. Я вижу, например, что он там не справился с запятыми, например, или какие-то формулировки, может быть, не очень точно использовал или какие-то двусмысленные и так далее. Короче, свою эту писательскую магию навожу в этом всем деле – какие-то правлю формулировки, структуру предлагаю новую. И показываю опять инженеру, говорю: «Вот я предложил правки, посмотри, как тебе такой вариант?» Он говорит: «Окей». И тогда мы вливаем эти правки в репозитории, и они появляются, соответственно, у пользователя на сайте. То есть это так вот подход этот выглядит. Инструменты, которыми мы для этого пользуемся, это обычные кодерские инструменты. Это те же самые, которые используют программисты для разработки кода. Это IDE. Ну, я вот, например, Visual Studio предпочитаю. И, соответственно, сборка. Тут тоже много разных движков есть, в том числе open-source, бесплатных и так далее. Тут как бы пространство велико, но про это, наверное, можно отдельно проводить… Какие движки, рассматривать их преимущества и так далее, их визуальную составляющую и прочее. Но второй ещё популярный инструмент у нас, конечно, остается Confluence. Потому что, скажем, если для пользовательской документации мы предпочитаем использовать сайт, то для внутренней документации, где, скажем так, требуется меньше формализма и порядка, если можно так выразиться, там, где любой пользователь может зайти и что-то написать, там мы используем Confluence. То есть для каких-то внутренних историй, чтобы, например, накидать какой-то план действий, накидать какую-то схему и так далее. То есть для внутренней доки в основном используются какие-то такие более простые инструменты. Также неплохой инструмент — это Google Docs, например, потому что Google Docs, в принципе, имеет все необходимые атрибуты, скажем так, хорошего редактора документации, хорошего инструмента, потому что он позволяет и ревью проводить. Ты можешь там оставлять комментарии в режиме комментирования, какие-то правки предлагать. Плюс, много людей может одновременно его править. Плюс, вся история версии сохраняется. Если что-то не так пошло, можно откатиться назад. И в целом это достаточно удобный инструмент. Его тоже достаточно удобно использовать в документации, но, конечно, до определенного предела. Инструменты, они, как, в принципе, везде и всегда, любой инструмент имеет некоторые границы применимости и целесообразность его использования. Где целесообразно, может быть, использовать Confluence и Google Docs, там лучше использовать Confluence и Google Docs. Ну, а там, где вам надо, чтобы у пользователя было все понятно и все было чистенько, и никакого разброда не было, то там лучше уже использовать серьёзные инструменты, как Docs as Code. Ты спрашивал ещё про рисунки, да?

Владимир Юсупов: Да, изображения.

Константин Макушев: Изображения. Вот что касается, например, скриншотов, то я вообще проповедую отказ от скриншотов, потому что скриншоты, я считаю, что они, в большинстве случаев, не работают. Просто не работают.

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

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

Владимир Юсупов: Извини, перебью тебя. Когда в тексте ты пишешь, нажми на такую-то кнопку, а сами пиктограммки добавляешь или просто только описанием?

Владимир Юсупов: Если это пиктограммка в виде рисунка, то можно добавить пиктограммку в виде рисунка. Пиктограммки – это окей. То есть показать, какая именно кнопка, это намного лучше, чем если мы напишем, например, нажмите кнопку с глазом. Взять эту кнопку с глазом и вставить ее. Нажмите кнопку, вот. Это, конечно, будет работать. Ещё к рисункам же относятся и схемы, что тоже важно. Особенно в концепциях часто используются какие-то схемы взаимодействия элементов, схемы расположения элементов, схемы ответственности людей… И вот схемы, конечно, это здорово, это нужно и полезно. Для их рисования можно пользоваться, в принципе, чем угодно. Я рисую схемы нечасто, поэтому даже не знаю, что посоветовать. Ну, у Visio, например, у майкрософтовского продукта есть неплохой набор инструментов для рисования схемок сложных. Но если вы используете Docs as Code подход, то я рекомендую вам посмотреть в сторону Mermaid Diagram. Это такой инструмент, который позволяет вам написать как бы код, в котором описать, что должно быть на диаграмме и как элементы на ней должны быть связаны. И на рендере получить готовый рисунок. То есть вы как бы рисуете рисунок в коде, текстом. И это очень хорошо сочетается с подходом Docs as Code, потому что во-первых, вам не надо рисовать, во-вторых, если что-то поменяется на схеме, вам не надо ее перерисовывать – вы можете просто зайти и поправить строчку, и в-третьих, наконец, у вас это видно очень хорошо в Merge Request’е. Видно, что изменилось. То есть ревьюер может посмотреть, что изменилось конкретно. В целом это намного лучше соотносится с подходом Docs as Code, чем вставка рисунков, которые нарисованы где-то в стороннем визуальном редакторе. Я рекомендую рассмотреть возможность использования Mermaid Diagram. Можете загуглить, найдете без труда.

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

Константин Макушев: Вот я рекомендую тебе посмотреть в сторону Mermaid Diagram. Там очень широкие возможности у них на самом деле. Там и блок схемы можно рисовать, и всякие там схемы взаимодействия, графики даже. Представляешь? Можно графики рисовать, прям задавать там значения, столбцы строить и так далее. Очень широкие возможности. Если хочешь, я тебе ссылку там скину на документацию официальную.

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

Константин Макушев: Здесь есть два таких важных аспекта. Во-первых, это языковая часть и предметная часть. Понятно, что по предметной части я не порекомендую чего-то единого. Но вот когда я работал переводчиком, то есть как бы работа переводчика тоже, как и техписателей, не заключается в том, что он сидит и по 8 часов печатает перевод. Она заключается, может быть, в меньшей степени, может быть, процентов на 30 состоит из того, чтобы разобраться в предметной области, по которой ты переводишь документацию. И чтобы это сделать, я, например, пользовался просто Гуглом, Википедией, какими-то сайтами или документацией аналогичных продуктов, чтобы разобраться, что происходит. Что в работе техписателя, что в работе переводчика, это очень важно. Для инженеров, может быть, это в меньшей степени актуально, потому что они, может быть, если они пишут документацию по своему продукту, они в нём уже разбираются. Но я думаю, что среди наших слушателей есть и те, кто работает как переводчик с продуктами, которые сам не разрабатывал. И здесь как бы такой совет: просто разбирайтесь, гуглите, уделите этому время. Может показаться, что это трата времени, но на самом деле в итоге окажется, что вы сэкономили время. Если вы потратили сколько-то часов или сколько-то минут на то, чтобы посидеть и разобраться, что же это за предмет, продукт и так далее, программа, что она делает. Это очень сильно экономит время. В техписательстве то же самое. Вы просто обязаны разобраться, что происходит. Что касается по профессии, то есть, что касается языковой части. Здесь, наверное, мои советы будут достаточно распространены, скажем так. Наверное, многие это советуют, это почитать Нору Галь «Живое и мертвое». Это помогает, так сказать, прочистить немножко мозги от канцелярщины и от тяжелых формулировок, скажем так. То есть ты, прочитав её, ты понимаешь, что тебе, оказывается, не надо вот это вот городить всё, то, что обычно принято в прежние времена было городить в документации какие-то официальные формулировки, а что можно писать более просто и прямо. И вторым пунктом, конечно, будет Ильяхов «Пиши и сокращай» как продолжение Норы Галь. Хотя с Ильяховым надо быть, конечно, осторожнее, потому что если перестараться, то можно получить текст столь же неестественный, как если бы он был написан канцеляритом, если слишком буквально воспринять все советы Максима. Также по текстам я обычно рекомендую Уильяма Зинсера «Как писать хорошо». Это в целом большой профессионал по нехудожественным текстам и у него есть даже отдельные статьи, например, по научно-популярному подходу и так далее. Также я бы рекомендовал, наверное, курсы. Если вы начинающий технический писатель, в интернете есть бесплатные курсы Семёна Факторовича. Также у нас есть большое сообщество в Телеграме, в которое я рекомендую присоединиться вам. Если вы пишете тексты так или иначе, неважно, технический вы писатель или вы пишете тексты как инженер время от времени. В общем, если вы пишете документацию, вступайте в наше сообщество в Телеграме. Я думаю, что ссылочка будет где-то в описании, да?

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

Константин Макушев: У нас будет где-то описание, да? Добавим туда ссылочки все необходимые. Ну и также на Хабре есть некоторые классные статьи про документацию. И не только мои. В целом, такие вот общие советы по книжкам. Вот я три книжки назвал. Я думаю, что это уже будет хорошей базой, чтобы именно с точки зрения языка прокачаться. И ещё, кстати, ну, про подход Diataxis мы уже сказали, да, можно почитать и нашу статью на Хабре, и, собственно, оригинальный сайт посмотреть. И если вы хотите быть на острие, так скажем, всех новых лучших практик, то рекомендую посмотреть видеозаписи Write the Docs. Она на английском, к сожалению, только, но… Там реально крутые технические писатели со всего мира выступают, и они рассказывают о тех лучших практиках, которые они в своей работе используют. И, может быть, там вы для себя что-то тоже интересное почерпнёте, но это уже скорее для advanced уровня совет. Скажем так, скорее всего, новичкам там будет непонятно, что происходит.

Владимир Юсупов: Спасибо, Костя. К сожалению, у меня вопросы закончились. Если ты, что-то хотел добавить, какие-то, может быть, темы, какие-то вопросы или, может, кто-то по озвученным вопросам хотел бы добавить, то, пожалуйста, можешь сказать что-то ещё.

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

Владимир Юсупов: Спасибо большое за дополнение. Кость, тогда я тебя ещё раз благодарю за уделённое время на беседу. Даже технические неполадки не смогли остановить нас.

Константин Макушев: Спасибо большое, Владимир. Было очень приятно с тобой пообщаться.

Владимир Юсупов: Спасибо. Надеюсь, что вот эта наша встреча третья, так скажем, виртуальная встреча. Твоя со мной первая, моя с тобой третья. Вот они будут не последние. И желаю тебе интересных задач, проектов, а также пусть и уходящего, но прекрасного летнего настроения. Буду ждать, кстати, твоих новых познавательных статей на Хабре.

Константин Макушев: Спасибо, Владимир. Буду стараться.

Владимир Юсупов: Спасибо, Костя. До встречи!

Константин Макушев: До свидания!

Владимир Юсупов: Спасибо, что прослушали этот выпуск.

Напоминаю, что вы всегда можете ознакомиться с текстовой расшифровкой на сайте подкаста.

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

До встречи!