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

На этот раз мы говорим о том, как адресовать свою документацию глобальной, non-native аудитории.

(да, речь в статье идет в том числе о Simplified Technical English и Global English)

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

Опубликовали на Хабре веселую статью о документации, адресованную начинающим IT-специалистам.

Злые нейросети, миграция архитекторов в Амстердам, героические инженеры техподдержки, стендап-комедия в командах разработки — казалось бы, причем тут техническая документация?

А вот!

А у нас новый учебный курс, на этот раз о ревью.

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

Этот курс рассказывает о приемах, процессах и этикете ревью технической документации.

В практической части курса мы проведем ревью фрагмента вашей документации по стандартам documentat.io.

27 мая — 6 июня 2024, онлайн.

Это тестовая группа, в ней всего 10 мест, поэтому успевайте записаться!

https://documentat.io/courses/review/

А вот и расписание курсов documentat.io на весь 2024 год.

Внимательные читатели найдут здесь целых три(!) новых курса.

❇️ Ревью документации: методы, приемы, процессы. Поговорим о видах ревью, о процессах вокруг него, об этикете и человеческой стороне проверки качества документации. В практической части курса разберем характерные проблемы технических текстов и проведем ревью вашего фрагмента документации. 27 мая – 6 июня 2024

❇️ Большой курс по ГОСТ. Полное погружение в ГОСТ для тех, кто с ним еще не сталкивался. Расскажем, чем работа по ГОСТ отличается от других техписательских задач. Научим писать и сдавать ГОСТ-комплекты документации. 25 июня — 5 июля 2024, еще одна группа будет набрана на декабрь 2024.

❇️ Документация API. Расскажем о принципах REST API, о современном инструментарии документирования API и о взаимодействии техписателя и команды разработки. Попрактикуемся в описании реального API с помощью Swagger. 5–16 августа 2024

❇️ Управляем командой технических писателей: семинар для техписателей-тимлидов и тех, кто готовится к этой роли. Масштабирование команды, профессиональный рост подчиненных, делегирование задач, настройка процессов, отбор и наем техписателей. 16–20 сентября 2024.

❇️ Экспресс-курс «Технический писатель»: короткий вводный курс для желающих начать карьеру техписателя. Немного теории, немного практических заданий, краткий обзор профессии и рынка труда. Каждый участник курса сможет написать несколько технических документов и получить по ним комментарии преподавателей. 24 сентября — 3 октября 2024, еще одна группа будет набрана на январь 2025.

❇️ Документация разработки: курс о документации, которая пишется разработчиками и адресована разработчикам: фиксация архитектурных решений (ADR), документирование программного дизайна и программной архитектуры (C4, arc42). Курс проводится только для корпоративных групп и только по запросу.

❇️ Бесплатный обзорный курс о технической документации: 12 лекций от представителей российского сообщества техписателей на разные темы: процессы документирования, инструментарий техписателя, docs-as-code, локализация, ГОСТ 19 и ГОСТ 34. Лекции курса доступны в YouTube-плейлисте или в телеграм-чате курса.

Все курсы проходят онлайн в формате живых вебинаров. Участникам будут доступны видеозаписи и материалы занятий.

За выходные мы укомплектовали группы на бóльшую часть только что анонсированных курсов. Спасибо вам за активный интерес к тому, что мы делаем!

Сейчас у нас открыта запись только на эти курсы:

❇️ Ревью документации: методы, приемы, процессы. Поговорим о видах ревью, о процессах вокруг него, об этикете и человеческой стороне проверки качества документации. В практической части курса разберем характерные проблемы технических текстов и проведем ревью вашего фрагмента документации. 27 мая – 6 июня 2024

❇️ Управляем командой технических писателей: семинар для техписателей-тимлидов и тех, кто готовится к этой роли. Масштабирование команды, профессиональный рост подчиненных, делегирование задач, настройка процессов, отбор и наем техписателей. 16–20 сентября 2024.

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

Если на каком-то из укомплектованных курсов освободятся места, мы немедленно анонсируем это в телеграм-канале @documentatio_official.

Наша статья про английский язык победила в номинации «Подготовка технической документации» конкурса «Технотекст 2023»!

Поздравляем автора статьи Костю Макушева!

Помаленьку начинаем публиковать на Хабре результаты большого техписательского опроса, который мы проводили в январе 2024.

Первая статья расскажет об основных, но очень важных срезах русскоязычного сообщества техписателей:

- В каких странах и городах мы живем?
- Сколько нам лет?
- Кого среди нас больше — мужчин или женщин?
- Сколько мы зарабатываем?

https://habr.com/ru/companies/documentat/articles/818199/

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

Не получилось ли так, что авторы опроса (я и documentat.io) планируют использовать эти величины для манипуляции рынком труда и для занижения зарплат в техписательских вакансиях?

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

Пост ответов на незаданные вопросы Юрия

Удивили ли меня результаты опроса в части зарплат?
Да я просто оху Очень удивили, да. Я был уверен, что медиана (особенно в регионах) выше.

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

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

Картельный сговор тут не работает никаким образом — всем выгодно максимизировать собственный наём в ущерб найму в компаниях-конкурентах, В чистом виде zero-sum game.

Факторович подрихтовал результаты опроса! Зарплаты на самом деле выше!
См. выше, делать так — подвергать риску мой собственный наём

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

Права техписателей с зарплатами в 200к+ ущемляют, теперь их будут прогибать по зарплатам!
Поверьте мне, у техписателей с зарплатами из 95-го процентиля всё хорошо: их активно хантят и перекупают, если они выходят на рынок труда, за ними выстраивается очередь работодателей, у них нет проблем с повышением ЗП на текущем месте работы. Опять же, в игре «найми сеньора» никому из работодателей нет смысла занижать зарплаты в ущерб собственной конкурентоспособности. Сеньоров на рынке такой дефицит, что работодатели готовы удерживать и привлекать их каким угодно способом.

Чьи права ущемляют, так это техписателей из регионов с зарплатами 90к и меньше (а их почти 50%, на секундочку). Именно эти техписатели должны показывать эту статью своим работодателям. Именно работодатели, нанимающие в регионах, должны корректировать свою зарплатную политику, чтобы быть конкурентными хотя бы в терминах «мы платим на 10% выше медианы Факторовича» — потому что это уже будет выше половины их текущего рынка.

Поэтому, дорогие мои сеньоры с зарплатой в 300кк/сек, этот опрос вообще не про вас. Этот опрос про ту часть техписательского сообщества, которая получает ниже медианы (еще раз: их ровно половина из всех опрошенных, в этом и определение медианы, и здесь уже даже не столь важно, насколько репрезентативна моя выборка). И одна из целей опроса — поднимать эту медиану год к году. В этом году умные работодатели в регионах увидят эту статистику и поднимут свои зарплаты на 10%-15%-20%. В следующем году опрос покажет, что медиана выросла до, условно, 140к, и работодателям снова придется повышать ее, чтобы оставаться конкурентными.

Зачем это всё мне? Потому что моя миссия — создавать и растить профсообщество техписателей. Сейчас нас мало и мы растем не так хорошо, как хотелось бы: мало людей приходит в профессию, много уходит в другие профессии. Работа с зарплатным рынком — один из способов оздоровить и расширить сообщество (один из, не единственный). И да, мой аутсорсный бизнес — всего лишь одна из активностей, которыми я в этом сообществе занимаюсь.

А вот и вторая статья о результатах нашего техписательского опроса.

На этот раз мы расскажем вот о чем:

- Как русскоязычные техписатели распределены по индустриям и отраслям? Сколько из нас документируют финансовые продукты, а сколько — самолеты?
- Сколько процентов русскоязычных техписателей никогда не используют ГОСТ?
- Как часто мы выполняем работу аналитика за втрое меньшую зарплату описываем требования?
- Как влияют на зарплату умения документировать API и описывать программную архитектуру?

https://habr.com/ru/companies/documentat/articles/819633/

Пожалуйста, выступайте на конференциях!

Конференционный доклад — супер-полезная активность для вашего профессионального роста. Это и отличная «лычка» для портфолио/резюме, и возможность сравнить себя и свою компанию с другими игроками рынка, и повышение вашей профессиональной видимости. Да-да, хороших докладчиков охотно хантят!

Вот две прекрасные российские конференции, где всегда рады докладам от техписателей:

🔹KnowledgeConf, 27–28 ноября 2024, Москва

🔹TechWriter Days, 28–29 марта 2025, Санкт-Петербург

На обе из них еще можно подавать заявки на доклады, но дедлайны уже близки: у KnowledgeConf крайний срок подачи 15 августа, у TechWriter Days — 1 сентября.

Если вы ждали знака, чтобы попробовать впервые выступить, то это он:) Рассказать о своих профессиональных достижениях и поделиться опытом с другими техписателями — что может быть интереснее?

А в качестве дополнительного стимула вот вам запись моего доклада на KnowledgeConf'23

«Запуск завтра»

Был очень польщен приглашением выступить в замечательном подкасте о технологиях под названием «Запуск завтра».

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

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

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

Но получилось всё равно интересно!

Послушать подкаст: https://share.transistor.fm/s/69dc5a2a

Выпуск покаста на YouTube: https://www.youtube.com/watch?v=QD2-bzEgpA8

В процессе написания статьи на Хабр (очередная статья о результатах нашего январского опроса уже почти готова!) как-то само сформулировалось определение парадигмы Docs as Code.

Что скажете о точности определения? Стоит ли что-нибудь добавить или поправить?

documentat.io неспешно ищет себе менеджера проектов.

120–180к на руки, полная удаленка, можно находиться вне РФ, можем платить на зарубежные банковские счета.

В идеале мы хотим видеть на этой позиции middle PM с опытом в аутсорсе или диджитале (опыт в процессах заказной разработки документации необязателен, мы расскажем вам всю специфику на месте).

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

Расскажите об этой вакансии знакомым менеджерам или примерьте ее на себя!

Докажите работодателю, что вы не робот

Поиск работы в 202х — хорошо автоматизируемый процесс.

◾️Можно написать скрипт, который будет ежедневно дергать API hh.ru, выгружать оттуда все интересные вакансии и автоматически на них откликаться.

◾️Можно сделать бота, который будет поддерживать разговор с HR-ом в мессенджере hh.ru или на LinkedIn — например, регулярно пинговать его и просить побыстрее рассмотреть отклик.

◾️Резюме и сопроводительные письма можно писать с помощью ChatGPT.

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

Поэтому если в отклике есть четкие признаки того, что это начало восстания Скайнета дело рук бота, а не homo sapiens sapiens, у HR-а есть сильное желание (часто подсознательное) отправить отклик в корзину.

Что делать, если вы настоящий человек, подаетесь на конкретную вакансию, и хотите, чтобы ваш отклик не отфильтровали как продукт жизнедеятельности нейросетей?

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

Все они основаны на реальной практике найма в documentat.io, ни одно событие не вымышлено, все совпадения неслучайны.

1. Живой человек откликается на вакансии, релевантные своему опыту. Бот откликается на всё подряд.

Вакансия: техписатель с 3+ лет опыта.

Отклик: водитель категории D (пассажирские автобусы).


Вакансия: менеджер проектов.

Отклик: Java-разработчик.


При этом абсолютно нормально, если явное несоответствие резюме и вакансии как-то объясняется в сопроводительном письме.

Например:

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

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


2. Живой человек внимательно читает вакансию целиком. Бот реагирует только на ключевые слова.

Вакансия: «На этой позиции не подразумевается разработка документации по ГОСТ. Ваш опыт в этой области не будет сочтен релевантным»

Сопроводительное письмо: подробное перечисление опыта, связанного только с ГОСТ.


Вакансия: junior-техписатель с минимальным опытом в Git.

Сопроводительное письмо: «Я junior frontend developer, хорошо владею Git, с удовольствием присоединюсь к вашей frontend-команде»

Читать продолжение

Докажите работодателю, что вы не робот, часть 2

(это продолжение, первая часть тут)

3. Живой человек напишет сопроводительное письмо под конкретную вакансию. Бот разошлет абсолютно одинаковый текст на сто вакансий.

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

И наоборот, если в сопроводительном письме виден живой интерес кандидата к компании, это всегда приятно.

«Проходил ваши курсы / видел вашу публичную документацию / слушал доклады ваших сотрудников, теперь хочу у вас работать»

А еще «веерные» сопроводительные письма иногда забавно не попадают в читателя:

«Впечатлен программными продуктами, которые выпускает ваша компания, хочу к ней присоединиться»

Да, большинство IT-компаний в России продуктовые, но не наша.


4. Живой человек пишет сопроводительное письмо сам. Бот использует ChatGPT.

На большом количестве откликов (на нашу прошлую вакансию менеджера проектов откликнулось 500 человек) стиль ChatGPT становится очень узнаваемым. Тем ярче на общем фоне видны сопроводительные письма, написанные самостоятельно и «пахнущие» личным, человеческим стилем.


5. Живой человек пишет в резюме правду. Бот галлюцинирует и придумывает то, чего нет.

Резюме: «С 2023 года работаю техписателем в московском офисе компании N»

Всё хорошо, только компания N еще в 2022 году закрыла все российские офисы и не работает с резидентами РФ даже по удаленке.


Резюме: «Два года работал техписателем в компании M, использовал там Docs as Code»

Так получилось, что я хорошо знаком с техписательской командой в M и знаю, что Docs as Code у них не используется. Пишу тимлиду команды в М, спрашиваю, работал ли у них имярек. Ожидаемо, о таком человеке там никто не слышал.

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

Читать продолжение

Докажите работодателю, что вы не робот, часть 3

(это продолжение, предыдущая часть тут)

Понятно, что автоматизированные отклики, экономящие время кандидатов и позволяющие «покрыть» как можно больше вакансий за короткое время — резонный ответ на новые реалии отбора и найма в компаниях.

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

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

Поэтому:

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

А если у вас нет времени или желания писать сопроводительное письмо, адресованное конкретному работодателю, то лучше не писать его совсем, нежели присылать шаблонное или «пахнущее» ChatGPT.

И да, приходите к нам работать!

◾️Junior cloud-техисатель без опыта работы, 60–90к

◾️Cloud-техписатель, 150–190к

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

В этой серии вы узнаете:

– Какой самый популярный документационный инструмент у русскоязычных техписателей (нет, это не Word).

– Сколько получают техписатели, умеющие в Docs as Code (гораздо больше тех, кто этого не умеет).

– Как идут дела с импортозамещением Confluence (пока не очень).

– Сколько техписателей используют DITA (меньше, чем вы думали).

Читайте, комментируйте, ставьте плюсики!