Что делают писатели в IT

Либо-либо. Всем привет!

Самат Галимов и это подкаст Запуск Завтра.

Как технический директор я пытаюсь разобраться, как устроены сложные и интересные штуки. Я зову профессионалов, с которыми можно поговорить простым человеческим языком. Сегодня мы будем говорить о документации. На самом деле, документация— это такой отдельный мир. Вот представьте, самый верхний слой— это мир, в котором мы живем и предметы, которыми мы пользуемся. А слой ниже— технологии, благодаря которым они работают. А документация— это еще следующий слой. Благодаря документации над проектами могут работать десятки тысяч людей одновременно. И при этом не получается вавилонская башня, которая развалилась из-за того, что люди не могли понять друг друга. При этом написание документации— это еще и отдельный навык. Не каждый, кто создал или работал над системой, может объяснить ее устройство другому. Сегодня мы поговорим с человеком, который не только умеет писать очень классную документацию и учит этому других, но и смог построить на этом отдельный бизнес. Это подкаст студии Либо-Либо. И этот эпизод мы сделали вместе с финтехкомпанией Точка. В середине выпуска вы услышите нашу партнерскую рубрику, в которой мы говорим о принципах разработки.

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

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

это и есть документация?

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

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

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

какой-то... Какая-то преемственность передачи.

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

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

А он спросит. Вот у нас есть команда небольшого стартапа, в которой есть сотрудник номер один, главный разработчик, вокруг которого все это, собственно, и наросло. И по мере развития стартапа в команде появляется другой инженер. И эти инженеры как-то причащались к мудрости старшего технического специалиста почти наверняка, когда новый человек приходил, какая-то вводная ему была дана старшим инженером, или, по крайней мере, старший инженер регулярно отвечает на вопрос. Говорить проще, чем писать. Говорить мы любим точно сильнее, чем любим писать. И раз старший инженер мог словами объяснить то, как устроена система другим инженерам, техписателю? Это накладывает некоторые ограничения на техписателей. То есть, техписатель должен в целом понимать все, что им будет сказано. То есть, есть какой-то стереотип, которыми меня часто пролетает, что техписатели в IT— это все как один бывший гуманитарий. Получили, условно, лингвистическое образование и пошли вкатываться в IT, потому что нигде другой работы не нашли. Ну вот мы в этом 24-м году проводили достаточно большой соцвопрос среди российского сообщества техписателей. И в том числе мы спросили о том, как люди в эту профессию попали. Техписателя с инженерным бэкграундом гораздо больше, чем с гуманитарным. Но даже если у техписателя инженерного бэкграунда нет, он не учился, не заканчивал компьютерные специальности, нет у него опыта программирования даже учебного. Добрать навыков, разобраться в том, как устроена программная система на том уровне, чтобы понимать, что тебе говорят, и писать это, совершенно выполнимая задача, она занимает там даже не годы. В общем, грубо говоря, Понимать, как устроены программные системы, для этого нужно гораздо меньше объема навыков, чем уметь их самому проектировать и писать. То есть это, в общем, вполне даже в рамках одной компании такой проходимый путь профессиональный.

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

Документация пишется либо для пользователей программных продуктов, причем пользователи бывают очень разные. То есть это могут быть пользователи-разработчики, которые GitHub Pages, настраивают что-то. Один из клиентов нашей компании— это Яндекс.Лауд. Большой набор облачных сервисов. Кто пользователь этих сервисов?

Программисты другие.

Разработчики или инфраструктурщики, да, там DevOps-инженеры, например, тоже пользователи, да. И человек, который веб-интерфейсом, это тоже пользователь.

Но совсем другой.

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

Про пользовательскую документацию, чем она отличается от того, как система устроена, мне хорошо понятно. А вот как отличаются B и C, то есть то, как система устроена, ты сказал, это вот типа второй тип. А третий тип—

это для тех, кто ее разрабатывает.

Чем они отличаются?

ТЗ техническое задание— это очень хороший пример документации из третьей категории. То есть мы рассказываем, как будет работать система, но это не про архитектуру, это про пользовательский сценарий, про юзкейсы, про то, как некоторые граничные точки, по которым можно восстановить какую-то оболочку того, что будет представлять собой будущий продукт. Такая поговорка, которую техписатели очень любят, что Чем техписатель отличается от аналитика? Аналитик документирует систему, которой еще нет, а техписатель документирует систему, которая уже есть. И вот эта проектная часть документации, она, во-первых, в меньшей степени про то, как все внутриустроено или как они пользуются, потому что еще ничего нет, у нас проекты еще идут. А во-вторых, она целит наименее технические штуки, она целит высокоуровневое описание фич. То есть это документация, которая описывает что-то, касающееся хода проекта, но в меньшей степени затрагивает то, как внутриустроено.

Если второе это такой артефакт, который можно условно продать вместе с системой, или там она должна идти в комплекте поставки вместе

с системой, то третье это как вода,

жизнь, как бы кровь проекта, которая описывает то, как он прямо сейчас живет.

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

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

Никто никогда не говорит, что документация— это текст. Фоточка маркерной доски, где написана куча квадратиков, соединена с стрелочками— это документация. То есть я, даже будучи разработчиком, многократно видел страницы в Confluence, которые состоят просто из фоточки доски, и это прекрасно работало. То есть эта фоточка отвечает на миллион вопросов, почему нет. В очень многих случаях, совершенно верно. Поэтому документация— это способ представить информацию. На самом деле, писатели скорее смотрят на документацию, как на способ коммуницировать. Мы же можем по-разному коммуницировать. Старший разработчик может сделать устный анбординг новому сотруднику, они могут созвониться, он может поотвечать на вопросы в рабочем мессенджере и написать письмо или ответить на письмо. Это все способы коммуникации, способы передать знания о системе. Документация один из них. Это такой интересный способ. Часто используется для него термин pull. Извлекать. Мы из документации извлекаем информацию. В чат мы написали в мессенджер. Это такой пуш-коммуникация. Мы пинганули человека, через сколько-то получили ответ. Есть real-time коммуникация. Мы сейчас с тобой созваниваемся.

Я тебя спрашиваю, ты мне сразу отвечаешь.

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

Или тебе это так сложно, что ты такой в какой-то момент думаешь, а ну нахрен, как бы, я не буду читать?

Я закрыл, закрыл, закрыл и пошел спрашивать. Да, это, кстати, тоже очень частый паттерн. Я думаю, тоже ты сталкивался, да, что документация не работает. А когда она не работает, коммуникация просто, ну, начинает течь по другим руслам. Да, я прочитал документацию, ничего не понял, закрыл ее и в Slack, спрашивать, чувак, ты ничего не понял, ничего не понял? Объясни мне с самого начала. Вот, поэтому, в общем, документация— это всего лишь форма коммуникации. Как она выражена? Текстом, записанным в видео. Тоже, кстати, кроме шуток, я работал в

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

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

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

Это супер ценно, потому что программистам приходится

объяснять, зачем они сделали ту или иную часть.

И если ты в начале недели не очень понимаешь, как ты будешь это продавать

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

Хочу двинуться дальше. Вот мы с тобой обсуждаем, что это такая живая штука, коммуникация, вот это все, но какой процент документации пишется просто потому, что у тебя есть обязательства там по закону, какой-нибудь ГОСТ, я не знаю, какой-нибудь ИСО, международный стандарт?

В России практически нет областей, где ты законодательно должен писать документацию. В любом там учебном курсе, который тебя писатели учат писать по ГОСТу, сразу говорится, что ГОСТ это не законодательный акт, не нормативный правовой акт, нигде практически нету законодательной необходимости по нему писать. Другое дело, что в очень многих областях в России контрактуальные обязательства между заказчиком программного обеспечения и исполнителем, в них иногда по дефолту вписаны требования принести по ГОСТу. Ну плюс есть еще работа в государственных структурах и на государственных структурах, где это тоже Правильнее, наверное, называть его контрактуальным, нежели законодательным обязательством. Это правда. А в социсследовании, которое мы проводили, мы спрашивали у российских писателей, пишете ли вы по ГОСТу, приходится ли вам это делать, и сколько вас дают. В России 44% писателей хотя бы иногда пишут по ГОСТу. Здесь важно, точнее, хотя бы иногда, потому что там спектр достаточно большой. Есть компании и бизнес-ниши, где документация пишется исключительно по ГОСТу, потому что заказчику только она и нужна. И в большинстве случаев, ты совершенно прав, ее не читают или читают формально, то есть это там некоторых такой формальный критерий приемки, то есть принесли пачку документов. Да, кстати, в некоторых областях до сих пор нужно приносить бумажно распечатанный комплект ДГС документов на бумаге, кроме шуток. Принесли, типа названия документов соответствуют тому, что было в контракте запрошено. Ну, все полегче. Где-то ее читают, где-то ее читают с пристрастием, и, например, проверяют там описанное в документе, описывающем архитектуру, соответствует тому, что в коде. Но в моей практике это происходит реже. гибридные случаи, когда какая-нибудь компания, продуктами которой мы пользуемся все каждый день, и документацию, которую, может быть, тоже мы читаем каждый день, которая выложена публично, лежит в вебе, должна какую-то часть своей документации писать по госту, потому что, например, они делают внедрение в государственные организации, и, опять же, по конструктуальным обязательствам им нужно предоставить, ну, покрыть каким-то комплектом госдокументов, предотцов. Поэтому это нужно. Да, в моей практике, по большей части, госдокументы не читают, но в целом вот, ну, даже статистика говорит, да, что техписателей. И в целом, опять же, там вот по тому, что говорят члены профсообщества техписательского, все-таки наши документации читают. То есть истории, что вот что-то написано полностью в стол, у нас это скорее исключение, нежели какая-то там постоянная история.

А вот эти официальные, стандартные, насколько они живые, насколько они полезные? То есть то, что ты им соответствуешь, это типа улучшает качество их документации?

Ну, define полезность, да? То есть что мы вообще считаем качеством документации, да?

Пройти гостендер очень полезно, да?

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

Нет.

Вот этих чудес там нет. Это один из способов покрыть документами проект по разработке программного обеспечения. Один из.

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

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

Пробовали читать документацию к Телеграму?

Вот ты смеешься, а я совершенно реальным образом читал документацию к WhatsApp. Она у него есть.

Офигеть.

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

Это не потому что они плохие, а они специальные.

Потому что их невозможно сделать так, чтобы все было понятно с самого начала. Вот вы, когда приходите в отделение банка ногами и что-то делаете, перед вами сидит операционист, и у этого операциониста на компьютере открыто внутреннее приложение банковское. как они называются, REM, кондиционное рабочее место, это дофига сложный софт. Там фич, ну не знаю, больше, чем суммарно во всех приложениях, которые у вас в телефоне установлены, и еще в 10 раз больше. Это просто функциональный, чудовищно сложный софт, который описывает, во-первых, сотни бизнес-процессов, во-вторых, эти бизнес-процессы очень нетривиальные. Ну и операционисты, они проходят обучение, во-первых, да, то есть у них есть какие-то обучающие семинары, где их хочется этим пользоваться, во-первых. А во-вторых, у этого продукта есть документация, и я эту документацию прямо читаю. То есть, у нее заходит, когда что-то непонятно, ее точно читают в процессе обучения. То есть, да, так получилось, что вот какой-то такой бытовой софт, которым мы каждый день пользуемся, да, ну кому? Зачем читать документацию к Инстаграму, да? Все же понятно. Но есть софт, где без этого просто нельзя.

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

Наверное, можно так на ситуацию смотреть, и, наверное, это хорошая цель профессионального роста UX-команды, да? То есть вот давайте мы вот такую глобальную, может быть, В целом, недостижимую цель себе поставим— делать UX так, чтобы документация была не нужна. с пользовательской документацией один очень интересный краевой случай. Главное, краевой, а в основной, в общем-то. Тот, в котором ее не читают пользователи сами по себе, по собственной воле, но скидывает пользователю техсаппорт. Пользователь не разобрался в чем-то, или он думает, что у него что-то сломалось, или у него сломалось, он пишет техподдержку или звонит техподдержку. И техподдержка, вместо того, чтобы каждый раз отвечать ему с нуля, да, писать ему сообщение, Это типичная ситуация. Нажмите вот на такую и на такую кнопку, просто кидается в нее ссылочка на уже давно написанную статью. Это совершенно реальный сценарий. И более того, этот сценарий очень интересно позволяет посмотреть на то, какую пользу пользовательская документация приносит бизнесу. Потому что если... Экономит время техподдержки. Если у техподдержки есть база знаний, да, публичная база документации, во-первых, сам факт наличия этой базы знаний, скорее всего, снизит некоторым образом... Количество обращений. Потому что какой-то, не все, но какой-то процент пользователей все-таки сначала прочитают документацию, и только потом пойдут в саппорт. А те, что все-таки дошли до саппорта, очень большой процент, там точно больше половины обращений в саппорт, можно будет закрыть, просто ответив, кинув ответ, ссылочку на какую-то уже существующую документацию. И в России, во всем мире, в том числе в России, есть компании, которые, например, через это выстраивают KPI и какие-то показатели качества работы своих целей. То есть давайте мы вообще глобально привяжем качество документации нашей пользовательской к какой-то динамике или к абсолютным или относительным значениям.

Обращение в саппорт, да.

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

Хочу про профессиональные инструменты еще личным опытом поделиться. Я еще школьником, мне кажется, был. Мне было лет 14-15, наверное. Я уже увлекался айтишечкой. Я покупал билеты на поезд в Казань, мне кажется, на Казанском вокзале в Москве. Я просто случайно увидел интерфейс, в котором кассиры РЖД-шные ищут билеты. И это просто командная строка. Там типа пустой экран, ничего нет. И она записывает, ты говоришь, там, хочу из Москвы в Казань, плацкарт, там, то-то-то-то-то-то, такие-то даты. Она забивает, типа, сокращенные имена городов, какую-то букву П, потому что это плацкарт, даты в каком-то своем формате, нажимает Enter, у нее таблица вылезает. Она, по сути, пишет SQL-запрос, на самом деле, к своей базе данных. Вот это без документации узнать, без специального обучения, невозможно. И должен ли быть там интерфейс очевидным? Ну, я не уверен.

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

Ты хочешь сказать, что там нет красивых кнопок просто потому, что у них технологии не позволяют?

Потому что инерция очень большая, и обновить им систему покупки билетов, которая 20 лет работает, прекрасно работает, им это стоит миллиарды, я говорю, что миллионы денег, и еще и бизнес-риски стоят себе гигантские. Обновление пошло не так, краевой юзкейс, поезда стоят, люди не ездят, ужасно-ужасно, то есть это лучше не трогать. И вот если этот софт вписался в эру, когда UX было еще не очень, когда у нас была черная окошко DOS, там важность документации, конечно, гораздо выше была. В этом смысле, безусловно, я к чему веду, что со временем, по мере развития Ну, не IT в целом, да, а, наверное, вот какой-то индустрии продуктов, программ. Конечно, ценность пользоваться MacMost в этом смысле падает от права. То есть мы действительно все больше и больше осваиваем сами.

Друзья, кроме основных эпизодов мы еще выпускаем бонусы. Например, в этом сезоне уже вышел бонус о том, кто и как торгует нашими данными в интернете. А еще о том, почему не все VPN одинаково полезны и как выбрать тот, который подойдет вам. Послушать их можно в закрытом Telegram-канале либо-либо или по подписке либо-либо плюс на Apple подкастах. Там же доступны все бонусы от других подкастов студии. Закаты Империи, Сабеса, Головы землекопа и многих других. Стримы с ведущими и подкаст «Студия» о том, как устроена наша работа. В июле либо-либо исполнилось 5 лет и в честь юбилея годовую подписку можно оформить со скидкой 50% за 1990 рублей. А если подписка у вас уже есть, подарите её другу. Ссылка в описании.

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

Да, да. Давай зайдем еще на шаг дальше. Технический писатель— это не та профессия, которой можно научиться в университете. То есть в российском образовании нет такой специальности. За последние 5-7 лет несколько вузов экспериментировали с этим направлением, российских вузов. Они открывали кафедры. И, по-моему, даже была одна бакалаврская программа, но какие-то из них даже закрыты на данный момент, какие-то там не сильно популярны оказались. Ну, в целом, российское образование Дарцуана высшее очень, да, и создать новую специальность— это задача на много лет, на 40 лет. Поэтому людей, у которых в дипломе написано «техническое писательство» в России, ну, если есть, то единицы.

Офигеть.

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

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

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

Восхитительная программа, вы будете очень рады.

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

Списками, заголовками.

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

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

Курсов, нацеленных на подготовку техописателей, не очень много. по Python, уж точно. Определенно меньше. Школ источников этих курсов в России, там, чуть больше пяти, да, точно меньше десяти. Так получилось, что моя компания, источников. У меня своеобразная история. То есть я работал в IT и учился на программиста. Довольно быстро я ушел в профессию техписателя, но все время, что я в IT был, с самого начала, я параллельно с фуллтайм работой в этих компаниях преподавал в Новосибирском государственном университете. И одно из направлений моего бизнеса, текущего в моей компании, это учебные курсы для техписателей. То есть мы вот тот самый источник этих курсов. Поэтому отвечаю на вопрос, конечно, мы берем выпускников в курсы, если это наши курсы.

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

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

А как найти первую работу с чиническим писателем?

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

Ты, кстати, несколько раз сказал уже June и Middle. Я точно знаю, что такая градация есть в программировании. Получается, у техписов тоже бывают June, Middle и Senior, наверное, да? Да.

И это очень интересная тема, потому что, поскольку во многих других отечественных профессиях эти градации, грейды, эти есть, наверное, очень резонно сказать, что они есть и в профессии технического писателя. Но поскольку профессия технического писателя в России в целом довольно молодая, ей меньше лет, чем профессии программиста, и ее какой-то такой бурный рост происходит вообще последние лет, 6-7, то есть лет 7-8 назад вакансии этих писателей были в России просто единицы. А вот там за последние лет 6-7 их стало сильно больше, тренд остается возрастающим. Профессия, короче, молодая. И универсального понимания, не то, что универсального понимания, чем джуниор-то писатель-человечец, его нету, но даже многие компании, имеющие, знаете, несколько таких писателей, на эти вопросы не могут ответить. Поэтому в целом каждая компания старается на эти вопросы отвечать сама, но если так какой-то общий знаменатель пытаться найти, Ну, наверное, как и везде, Джун— это тот, за которым нужно присматривать и доучивать, работу которого нужно проверять и который сам себе задачу, скорее всего, не поставит. Миддл— это человек, проявляющий большую самостоятельность и в качестве работы, то есть за ним надо меньше проверять, и он, получив какую-то крупную, нераздробленную на мелкие задачи, поймет, что с ней делать. А Синер— это тот, кому ничего не надо объяснять, не нужно за ним следить, и он сам за всеми может следить, менторить Джунов и так далее. Ну, в целом, все примерно к этому сводится.

То есть в большинстве случаев сам себе может поставить задачу, если дать ему направление.

Да, да.

Блин, я не могу не спросить, кто обычно отвечает в компании за документацию?

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

Четыре часа— это очень хорошо. Хорошо, что не неделю.

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

Он знает своих пользователей, в конце концов.

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

Потому что к ним приходят, когда проблемы.

Да, да. И вот эта связка, когда внутренним заказчиком документации является техподдержка, она великолепна. Почему? Потому что техподдержка, во-первых, прекрасный источник информации. Она знает, что отвечать. Она знает, что должна быть в документации написано, чтобы ее не дергали. Она сделает нам очень хороший ранжир вопросов, что по этим фичам продукта нам вопросов вообще не задают. Мы вообще можем их не описывать в документации. А по закону Парето по этим 20% фич нам 80% задаются. Поэтому, пожалуйста, опишите их. Это прекрасное сочетание счастливых компаний, которые к этому приходят.

Может быть, техподдержка и должна писать эти тексты?

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

на... Confluence.

Он похож на кладовку в хрущевке, в которой живет 50 лет одна и та же семья.

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

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

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

Это работает. То есть, техписатель— это профессия, действительно, с не очень высоким порогом входа. И то, что мы видим по профессиональным сообществам, действительно, миграция в другие направления высока. По миллиону причин техписателям платят меньше, чем разработчикам. Опять же, вот наше исследование говорит, что медиальная зарплата техписателей в России, там, на треть меньше, чем у разработчиков медиально.

А сколько примерно?

Медиана у техписателей 120 в России, а медиана у разработчиков 160, что такое, по-моему.

Это совсем неплохо.

Да, начало этого года, если я не путаю. Ну, то есть верхние 5% самых высокоплачивающих техписателей в России получают 240+, ну, но их 5%, да? Короче, меньше, чем разработка получает. Ну, во-первых, это смущает, а во-вторых, мы говорили о том, что сама профессия еще не вполне зрелая, и не все компании готовы дать писателям длинные, далеко идущие на годы вперед треки, росту. Писатели очень часто упираются в профессиональный потолок. Вот моей компании нужно писать только такие документы. Вот я поддерживаю эту базу знаний и поддерживаю уже 7 лет, что мне дальше делать, да? И куда мне расти? Я ничего нового не узнаю. И вот это тоже бывает частой причиной перехода в другие профессии. Люди переходят, да, почему нет? То есть техписатель достаточно сильно интегрирован во все процессы, и в разработку, Менеджмент. И переметнуться куда-то еще, стать даже менеджером, например, продуктом. Совершенно реально.

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

Во-первых, опять же, мы из нашего соцопроса с удивлением узнали, что структуры техписательских команд в российских компаниях очень разные. Где-то в компании есть команда техписателей целостная, то есть такой сервисный отдел, который получает запросы на документацию и там что-то с ними делает. А где-то в компании нету команды техписателей, они рассредоточены, каждый живет в своей там фирме. Бытовые команды, например, и эти типописатели вообще с друг с другом даже не знакомы, бывает так. Иногда в компании там несколько изолированных друг от друга команд типописателей, или неизолированных, которые управляются, например, один-одним, там, какими-нибудь супер-мега-тимли-дом-типописательскими. А иногда в компании ровно один типописатель, и он, собственно, вот всё, и швец, и жнец, и нынде и грец, всё обслуживает, турирельный историк. Соответственно, нужно думать о соотношении чего к чему. Общего хэдкаунта компании к техписателям. Или в конкретной инженерной команде сколько техписателей, сколько инженеров. Интересно, да? Вот я на заре своей карьеры работал техписателем в инженерной команде в маленьком R&D отделе большой компании. У нас там было соотношение интересное. У нас было 11 инженеров и 4 техписателя. И вот эти 4 техписателя обслуживали только эти 11 инженеров. Ну мы там по хардкору просто... Нифига себе. Это совершенно прекрасная была история, что компания осознанно искала техписателей, которые могут читать код на плюсах, схожий с системной софт, общаться с разработчиками на этом языке, и вот я первый техписатель в этой команде. В смысле, бывают люди, которые знают C++ и при этом готовы писать документацию, давай к нам, типа, все. Очень прикольный был момент. И я нашел трех таких же еще потом себе в команду техписателей.

Охренеть, вообще!

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

Насколько большая потребность рынка в техписателях? Ты говоришь, я техписатель, тебя отрывают с руками?

Скорее, да.

Или ты там ходишь, ныкаешься и ищешь?

Скорее, отрываются руками.

Почему?

Потому что компании год за годом в России поднимают важность документации. То есть, ну, это прямо на моих глазах происходит, там, за последние лет 10 очень активно. Компании, ну, я так скажу, поднимают важность документации. Может быть, не техписателей, но документации. То есть, они, ну, начинают говорить в тех терминах, какие говорим с тобой мы, что документация— это Экономия времени на коммуникации— это снижение риска того, что какая-то информация потеряется в месте человека. И в целом довольно несложно все это проследить до чистых денег или до каких-то важных бизнесов вещей, что если у нас выйдет ключевой разработчик со всякими уникальными знаниями, у нас бизнес не встанет, но мы, скорее всего, не сразу восстановимся из этой ситуации. Если мы снизим время анбординга с 4 месяца до 4 дней, мы немало выиграем в зарплате разработчика, который платит ему за то, что он не делает такая работа. И, в общем, вот эта вот какая-то культура документирования понимания важности растет, и российские компании нанимают, кстати, все больше и больше. То есть, больше компаний высказывают потребности в писателях, а компании, у которых они есть, расширяют свои команды. То есть, вакансий год от года становится сильно больше, зарплата тоже растет.

Кайф. Поехали про бизнес. Я слышал, я специально подробно это не изучал, но я слышал, что у тебя есть бизнес в области документации. Что ты продаешь?

У меня есть компания. documentat.io. Слово «документация» всего лишь просто. У нас два бизнес-направления. Первое бизнес-направление— нам нужно аутсорсить разработку документации. Мы техписатели из-за сервиса. Ну ладно. Это громкая и мутная фраза. Вот есть компании, которые разрабатывают сайты на заказ, мобильные приложения, аутсорсная разработка, диджитал, объемство, да, вот все вот это вот, если вместе перемешать, перемножить, мы точно такое же, только мы не делаем сайты, не пишем мобильные приложения и не разрабатываем решения на 1С, мы только пишем документацию. То есть нам можно отдать проект по разработке какого-то конечного фрагмента документации, нам нужно что-то зааутсорсить, у нас можно взять их писателя в аутстайфинг на потенциально бесконечный труд. Второе направление— это образовательная. То есть мы проводим у нас линейка из восьми образовательных курсов, нацеленных на тех писателей, на инженеров, которым нужно писать документацию, и мы с удовольствием. И плюс еще, помимо этой линейки, к нам приходит очень много корпоративных заказчиков. Мы читаем кастомные корпоративные курсы для российских IT-гигантов в том числе.

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

Если вот смотреть по бизнесам, то наши заказчики— это очень разный бизнес. Это стартапы небольшие, маленьких не бывает. То есть, мне кажется, наши услуги становятся интересными для команд от 25 человек. То есть, если стартап меньше, они, скорее всего, в документацию вкладываться еще не готовы. А у нас есть среди клиентов очень крупная российская Один из наших клиентов— это Яндекс.Клауд. Мы часть документации для Яндекс.Клауд пишем, мы не единственные у них авторы документации, но на сайте у нас можно посмотреть на наш послужной список. То есть это очень крупная российская IT, российская IT поменьше и совсем маленькая российская IT в том числе. Причем, что интересно, что характер заказов тоже очень своеобразен. Иногда к нам приходят компании, у которых нет документации вообще, они говорят, слушайте, вот у нас есть продукт, напишите на него пользовательскую документацию. Это там, ну, в немалом количестве случаев довольно разовая история. Мы посмотрели на продукт, разобрались, написали, отдали, получились. Иногда в этой ситуации они говорят, а еще поддерживайте, да, потому что продукт развивается, соответственно, документацию тоже нужно обновлять, и мы там сначала садимся и пишем, а потом там уже неспешно с очень маленькой загрузкой поддерживаем. А самое интересное начинается, когда к нам приходят компании, у которых уже есть команда техописателей, и они чаще всего говорят, нам не хватает рук, дайте нам еще несколько людей. Каким-то заказчиком мы целые команды формируем, и они на них работают. В этом смысле весь спектр. Кто является нашим персональным заказчиком, кому это нужно? Вот ровно те самые заказчики документации, о которых мы с тобой говорили. Короче, самый частый сертифицированный заказчик наших услуг— это CTO, технический директор. Он приходит и говорит, ребят, вот я вижу, что мне вот в моем коммуникационном поле, да, в моей команде не хватает того, чтобы что-то стало твердым, превратилось в документацию, давайте работать над этим.

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

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

Очень круто. Какой у тебя был самый сложный проект?

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

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

Вот, и мы все здесь правы, да, то есть прав бизнес, в котором он действительно, если мы перепишем это более понятно, вряд ли он увидит измеримые какие-то результаты, это вряд ли. То, что мы перепишем существующую документацию, сделав ее там лучше структурировать, да, там лучше оформить вот, собственно, о чем мы говорили. Не портянки текстами без разбиения на абзаце, а там коротенькие разделы, списки, таблицы. Вот если мы так перепишем, Вряд ли они увидят какие-то бизнесовые метрики этого. Вряд ли это значимо уменьшит обращение в саппорт. Уменьшит, но не скажет, что это на уровне флуктуации каких-то рядовых. И мы начали их уговаривать, что все-таки нужно переписать. Мы приносили им доводы вида. Вот текст будет понятнее, а здесь вот ошибка. Смотрите, у вас тут еще, поскольку разные люди писали, прям видно, что вот этот раздел писал один человек, вот этот другой. Там стиль очень сильно неконсистентный. Они такие, типа, ну что это? Почему это важно все? В итоге мы не сразу, мы пришли вот к чему, что на самом деле, нам помимо того, что документацию надо переписать, нам ее неплохо бы смигрировать на другой инструмент. А ребята все писали в Word, то есть этот документ, это был 300-страничный DocXFile. Мы говорим, а вот когда вы ввели эту документацию, вам как ее обновлять вообще было? Они говорят, так себе. А как у вас, например, там совместное редактирование, если нескольких писателей вы редактируете? Так себе. Мы говорим, смотрите, мы сейчас вам сделаем все, как принято нынче в лучших домах Европы. Ну и раз об этом речь зашла, собственно, не так давно появившаяся проригма инструментальной разработкой документации называется Docs as Code. Давайте относиться к документации как к коду. И вот действительно, там лет 10-15 назад, наверное, большая часть документации действительно писалась в Word. Сейчас, если вы заходите на какую-то публично доступную документацию, она, во-первых, вся держит в Web, как мы прекрасно знаем. Вся документация, которую мы читаем, мы читаем из браузера. Вы, скорее всего, заходя на какую-то публичную документацию, видите много разных страничек, и это всегда статика, это всегда статический HTML, то есть это почти никогда не CMS, это какая-то динамическая генеряющая контент-база. Это статический HTML, HTML вот сгенерен из легковесных языков разметки, например, Markdown.

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

Да, и в него что-нибудь законтрибьете, да. И есть набор инструментов, их писатели чаще называют сборщики. Это чаще всего опенсорсные или там надстроенные опенсорсные решения, которые берут пачку маркдаун файлов и собирают из них красивый HTML-портал с кросс-ссылочками, там с картиночками со всем, всем, всем. С поиском, да, поиск. Отдельная история, очень сложная документация. И мы говорим, давайте мы мало того, что перепишем, мы возьмем наш бордовский файл, переколбасим его в Markdown и настроим вам pipeline публикации, чтобы у вас вся ваша документация хранится в бите, и по пушу в какую-то ветку или просто по нажатию на кнопки у вас она будет публиковаться в тот же самый DocX, какой и был. То есть есть инструментарий, который из Markdown собирает DocX. И с идентичным контентом мы вам отдадим пачку HTML, которую вы выложите на сайт. И вот здесь всё было продано, то есть, да, всё, вот здесь мы видим вэлли, да, но раз уже за это берётся, тогда и перепишите, как считаете нужным. Ну вот, это был сложный разговор, мы делали, мы сложновато, потому что там, опять же, были ограниченные сроки и бюджет, но было интересно.

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

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

Классно. Сколько у тебя людей в компании?

У меня в компании 25 человек, из них 18 фултаймеров.

Обалдеть, то есть 18 технических писателей в компании.

Ну там их чуть меньше, кстати, примерно 18, да, получается, перемешка фултаймеров в портале, непонятно, там есть менеджмент, аккаунт менеджера, вот их пятеро. Да, у нас 20 писателей, да, получается

так. Очень похоже на мои размеры компании. Сколько стоят ваши услуги?

Сколько стоит сделать сайт, да?

Ну, я про это и спрашиваю. Я научился, наконец-то, отвечать. Типа, не меньше трех миллионов рублей у нас. Очень понятно.

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

Очень, мне кажется, нормально. А по времени, типа, как раз пару месяцев, наверное, да?

Даже меньше. Среднее полтора, наверное, было для таких проектов.

Многие слушатели— это программисты или менеджеры, которые занимаются разработкой софта.

И вот с чего стоит начать, если

в компании прямо все очень плохо с документацией?

Вообще, как ни парадоксально, наверное, написать мне или поговорить со мной. Совершенно серьезно, достаточно много контактов с компаниями. У нас, конечно, с тем, что мы просто часок говорим, никто за это несколько денег не берет, никто не выливается в какие-то там контракты или совместные работы, но я с удовольствием всегда отвечаю на вопросы именно уровня такого, о котором говоришь ты. Обычно знаешь, я бы эти разговоры свел к тому, что какой-то технический стейкхолдер, ЛПР, какое-то лицо, принимающий решение, чувствует, что у него с документацией что-то не то. Он не может объяснить это ощущение, но вот он чувствует, что что-то не то, и вот такие разговоры я с удовольствием провожу. Послушать, что не так, сказать, чуваки, дальше можешь не говорить, дальше я знаю, что у вас происходит, потому что в 90% компаниях все то же самое, и тебе нужно сделать вот это. А дальше просто в каждой конкретной ситуации решения разные. То есть где-то просто наймите техписателя, С рынка совершенно понятно, что писать, он сядет и напишет. Или, там, вам нужно отстраивать процессы с нуля, вы можете нанять тех писателей, но это должен быть сеньор этих писателей с опыта управления командой, потому что у него руки, ну, он знает, как процессы настраивать. Или, там, не знаю, купите у нас услуги, да, здесь мы вам поможем быстрее, чем вы полгода будете на рынке человека искать.

А какие самые частые проблемы, может быть, самые частые затупы, которые у компании есть?

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

И что тогда делать?

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

Очень круто.

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

Ссылка на курс будет в описании к этому эпизоду. Поехали дальше. Что можно... Вот я типа послушал этот эпизод, посмотрел и думаю, классная тема, хочу больше узнать, хочу почитать, разобраться. Книжки, телеграм-каналы, подкасты, ютуб. Что посоветуешь?

Техписатели есть, по поводу чего-то, одна большая площадка общения, это за вами желтый чатик техписателей, ссылка на него тоже будет в описании. Это телеграм-чатик на четыре с половиной тысячи человек, где, в общем-то, сядут уж точно подавляющее большинство техписателей российских и инженеров, которые темой документации интересуются. И в этом чатике есть замечательно запиненное сообщение, где мы свели все известные нам телеграм-каналы про документацию. И вот там нужно выбирать на любой вкус. Ладно, нет, один канал я порекомендую. Это канал Коли Волынкина, довольно известный товарищ в русскоязычном сообществе. У него канал про тот самый Docs as Code, про парадигму, к которой мы относимся к документации как коду, и обсуждая способы хранения документации в ВИТе, способы ее представления, способы ее трансформации из Markdown в другие виды. Вот, Коля, если говорить про инженерную аудиторию, я бы, наверное, порекомендовал очень классную книжку. Она называется The Product is Docs. Продукт— это документация, или можно прочитать, как документация— это тоже продукт. Насколько я знаю, ее на русский не переводили. Это книжка, которую написали сотрудники американской компании Splunk, и они рассказывали свой опыт о том, как они вот приходили к какому-то видению инновационной культуры вокруг инженерных команд. Это очень хорошая книжка.

Семен, спасибо огромное. Очень классный разговор. Спасибо тебе большое.

Спасибо. Спасибо за классные вопросы.

Друзья, пока вы ждёте новый выпуск, я рекомендую вам послушать ещё один подкаст студии Либо-Либо. Он называется «Любить нельзя воспитывать» и ведёт его педагог Дима Зитцер. Диме звонят родители, дёти, сёстры, племянники и бабушки со всего мира и задают вопросы о взаимоотношениях взрослых и детей. Что делать, если дочь подросток ничего не хочет? На что обращать внимание при выборе школы? Как говорить с ребёнком о деньгах? О том, как детям и взрослым строить доверительные, надёжные отношения и получать от них удовольствие, слушайте в подкасте «Любить нельзя воспитывать». Ссылка в описании. Это подкаст студии Либо-Либо, и этот эпизод мы сделали вместе с финтех-компанией Точка. Над эпизодом работали редакторки Маша Агличева и Рита Берденникова, продюсер Данил Остапов, звукорежиссер Юрий Шустицкий. За джингл спасибо Алексею Зеленскому.

Редактор субтитров А.Синецкая Корректор А.Егорова