Айтишник PRO • Путь технического писателя

Как общаться с иллюстратором/дизайнером? Раньше при написании статей я не имел дело с иллюстраторами. Накидывал креативы сам. Находил что-то интересное в интернете и изменял под себя в Canva. На днях пришлось столкнуться с постановкой задачи иллюстратору. Пишу статью для блога своей компании, а там, сами понимаете, корпоративный стиль. Скинул статью дизайнеру, кратко написал постановку — свою идею, какую обложку для статьи я вижу. И получил такой ответ, цитата: «Мне непонятна не идея статьи, не формулировка идеи для иллюстрации...» Я искренне полагал, что иллюстраторы, прочитав текст, могут сгенерировать миллион идей и предложить автору статьи на выбор. Потом мы бы вместе докрутили до идеала. Невероятным удивлением для меня было, что автор должен сам сгенерировать идею и еще ее подробно расписать. А иллюстратор просто воплотит в картинку. Не знаю, может это дизайнер у нас такой, или они все такие, или просто я такой отсталый в этом плане 🤷🏼‍♂️

3 ключевых навыка успешной карьеры техписателя 1️⃣Критическое мышление. Не верьте никому, пока сами не проверите. Если аналитик пишет в техническом проекте, что поле имеет тип DATETIME, перепроверьте в самой базе данных, там легко может оказаться тип TIMESTAMP. 2️⃣Декомпозиция цели. Разбивайте большую задачу на мелкие. Вот вы решили поклеить обои в комнате, вы же не сорветесь в ту же секунду покупать и замешивать клей? Сначала прикините сколько рулонов нужно, подумаете, как расставить мебель на время ремонта, выберите обои, оторвете старые и так далее. Также и с рабочими задачами. 3️⃣Умение действовать. Определили мелкие задачи для достижения большой цели, осталось самое важное — действовать! Сделайте первый шаг прямо сейчас. Второй пойдёт легче. Вообще, эти три компонента помогут достигнуть успеха в любом направлении. Не обязательно только техписателям.

Почему страдательный залог заставляет читателей страдать? Деньги потрачены, документ прочитан, программа протестирована, бутерброд хищно съеден —  во всех фразах подлежащее не выполняет действие, а испытывает его на себе. Это и есть страдательный залог. Но что же в нём плохого? ⚠️Проблема в том, что в тексте появляется неясность: кто же на самом деле выполняет действие? Если это просто бутерброд — ну съеден он да съеден, а если это большой вкусный сэндвич, который вы сделали утром и принесли на работу? Вот вы решили пойти на перерыв. Заварили кофе, открываете холодильник, а сэндвича нет, он был кем-то беспощадно съеден. В таком случае субъект действия очень даже важен 🤨 ❗️Также и в технической документации. Вот самый простой пример: «Перед обработкой файла создается его резервная копия». ❓У читателя возникнет вопрос: резервная копия файла создаётся кем, системой или администратором? 1️⃣Вполне может быть сценарий, что перед тем как запустить процесс отработки файла, администратор должен сделать его копию. 2️⃣А может и быть ситуация, что администратору требуется только запустить процесс обработки, а система уже сама сначала создаст копию файла и только потом начнёт обработку. 😀 Тогда как написать правильно? В 1️⃣случае пишем: «Перед обработкой файла создайте его резервную копию». Во 2️⃣: «Перед обработкой файла система создаёт его резервную копию». Согласитесь, с такой формулировкой не возникает никаких вопросов ▫️ ❌ Допускать в технической документации неясности — это категорически непозволительная роскошь. Я бы даже сказал: грубейшая ошибка! Посмотреть больше примеров со страдательным залогом можно в статье моего коллеги.

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

В каком случае IT-компании нужен технический писатель Один из ключевых моментов — это когда все способы коммуникации по программному продукту становятся дороже, чем текст. 🤘Процесс разработки документации не дешевое удовольствие. Средняя стоимость за разработку технического текста в 50 стр. от 80 до 130 тыс. В зависимости от сложности. К программному продукту обычно требуется 4 документа. И это минимум 320 тыс. рублей. ❕Но даже при таких условиях этот процесс может оказаться выгоднее, чем остальные. ➡️Например, компания разрабатывает IT-системы на заказ. В квартал сдаёт 1-2 новые системы. После внедрения и запуска её необходимо поддерживать. Сделать это можно одним из следующих способов: 1️⃣Взять систему на поддержку под свое крыло. 2️⃣Возложить эту обязанность на специалистов заказчика и дать им сопроводительную документацию. 🧍‍♂Один сотрудник поддержки стоит около 80 тыс в месяц с учётом всех взносов и налогов. На одну систему нужно 4-5 специалистов. Учитывая, что количество систем будет расти, штат поддержки увеличится за год ещё на 3-5 человека. То есть цена отдела в месяц уже будет 500-800 тысяч. Поэтому дешевле будет вариант 2️⃣. Так как в 1️⃣ случае потребуется собственная команда технической поддержки, которую придётся постоянно наращивать. Количество клиентов пользователей системы заказчика будет расти, а значит и будет расти количество заявок в поддержку. Содержать штат поддержки невыгодное дело ещё и потому, что в этой роли есть тенденция постоянной текучки кадров. И каждого нового специалиста нужно обучить поддерживаемым системам. ➡️В последнее время всё больше IT-компаний осознают это, благодаря чему, растёт спрос на технических писателей. А со спросом растёт и предлагаемый уровень ЗП 😎

👩‍💻 Часть 2 про выгорание — «Семейный день» ⬆️В прошлом посте я рассказал про такое опасное состояние в работе, как выгорание, и два действенных способа, как не довести себя до такого состояния. Один из таких способов — правильно отдыхать и уметь переключаться. Мы с женой придумали — «Семейный день». Один раз в неделю (у нас это воскресенье) мы полностью отключаемся от работы. Не переносим никаких рабочих задач на этот день, даже 30-ти минутных. С утра берём дочку и едем отдыхать. ❗️Крайне важно именно куда-то выехать. Просто побатониться дома не вариант. Чтобы полностью переключиться и не думать о работе, нужно сменить обстановку. Обязательно должна быть какая-то активность. Что мы обычно делаем: ходим в театр, в кино или ресторан (дочку оставляем на пару часов у бабушки с дедушкой), возим дочку в игровые центры, гуляем в лесу, гостим у родственников. Но допоздна не засиживается, возвращаемся домой так, чтобы ещё осталось время немного поваляться и восстановиться. Работу в этот день не обсуждаем и в рабочие чаты не заходим. ✔️Мы ввели такую практику буквально в этом году и уже восхищены результатом. Раньше, жена могла перенести на воскресенье занятие с учеником (преподает английский у подростков) и нам приходилось подстраиваться под это. В таких случаях максимум мы могли выйти погулять по району. Но это совсем не то. Я тоже мог взять работу часа на 2 в выходной день. В итоге, в понедельник ощущение как будто работаешь без выходных. Пара-тройка месяцев в таком режиме и вот вам первая стадия выгорания. После того как стали раз в неделю полностью переключаться, настрой на рабочую неделю стал всегда позитивным и появилось больше энергии. Вечером в воскресенье нет мысли: «блииин, завтра на работу...». Вместо этого наоборот — «Ура! Завтра на работу!» 👍 Но, конечно, такое состояние не достижимо без ещё одной составляющей — найти дело по душе. Обо всех IT специальностях я напишу статью на VC, выйдет на этой неделе. А вы берете работу на выходные? Какими способами

❗️Почему я не пошел в DevOps. Часть 1. Кто такие инженеры DevOps, и почему это направление такое популярное. Когда я, ещё пару лет назад, заходил на hh и вбивал фильтр по ЗП в IT направлениях, то одними из самых оплачиваемых вакансий выскакивали «DevOps-инженеры». Уровень гонорара — до 450 тысяч рублей! 💲 Увидев такие цифры, появлялось чувство досады — как это, кто-то безо всякого бизнеса зарабатывает такие деньги ‼️ ✅Конечно же, первым делом я загорелся идеей стать DevOps. Но нужно было сначала подробнее разобраться с этим направлением: ➖какие задачи выполняют, ➖что нужно изучать, чтобы претендовать хотя бы на джуна, ➖и есть ли у меня шансы. Я изучил талмуды информации в интернете, просмотрел десяток интервью с девопсами и даже пообщался с коллегами, кто выполняет функции девопс и считает себя таковыми. Если очень коротко, то DevOps — это специалист техподдержки разработчиков и бэкенда системы. Если подробнее, то DevOps: ➡️настраивает среду для разработки системы (поднимает виртуальные машины, настраивает необходимые компоненты и инструменты); ➡️настраивает мониторинг среды разработки и реагирует на инциденты (то есть, если что-то не так, мониторинг подает сигнал, и DevOps разбирается в чем дело и чинит); ➡️автоматизирует процессы разработки (выкатка фич на продуктивную или тестовую среду в автоматическом режиме). Это основные обязанности чистого DevOps. Но, если пообщаться с девопсами в разных компаниях, то выяснится, что каждый занимается разными задачами. Кто-то работает больше с серверным железом, кто-то больше автоматизирует и программирует, а кто-то вообще работает с сетями или интернет безопасностью. В общем, чистых DevOps редко когда встретишь. В основном — это системные администраторы высшего уровня. То есть специалист уже не обслуживает компьютеры и принтеры сотрудников. Не настраивает им программы и не решает их проблемы. Он занимается инфраструктурой программной разработки. То есть девопсов можно встретить только там, где есть разработка систем

❓Почему я не пошел в DevOps? Часть 2. Обязательные навыки. В первой части я рассказал, кто такие инженеры DevOps, и чем они занимаются. Вот этот пост, кто ещё не читал. Сегодня расскажу, какими навыками нужно обладать, чтобы претендовать хотя бы на начальную (junior) позицию. А в третьей части поделюсь своими причинами, почему несмотря на высокую зарплату девопса и возможность им стать, я отказался от этого направления. 1️⃣Так как девопсы работают с серверной частью (бэкендом) системы, то обязательным навыком является знание сетей — стек TCP/IP и как все работает по модели OSI. Без этих знаний вы не сможете настроить ни сервер, ни инструменты, ни мониторинг. Следовательно и собеседование не пройдете. 2️⃣Необходимо понимать, как строится микросервисная архитектура. 3️⃣Уметь работать с системой контроля версий GitHub и его платными аналогами. 4️⃣Знать инструменты мониторинга серверных систем. Например, Zabbix, Cacti, Prometheus, Grafana. 5️⃣Уметь писать несложные Bash скрипты. 7️⃣Хорошо знать Linux и уметь его администрировать (RedHat, РедОС, Centos, Solaris, Ubuntu). 8️⃣Быть знакомым с инструментами систем автосборки (Jenkins). 9️⃣Уметь работать с Docker Compose, K8S, Ansible. 1️⃣0️⃣Уметь администрировать базы данных. 1️⃣1️⃣Понимать, как работают и настраиваются CI/CD-процессы. 1️⃣2️⃣Уметь работать с веб-серверами Nginx, Apache, IIS. 1️⃣3️⃣Уметь разбираться в логах систем, быстро реагировать на инциденты, находить и устранять причину проблемы. Нехилый такой список для позиции Junior 🤓 Это еще не все, а только основное. В зависимости от стека компании могут добавляться еще знания некоторых технологий. Но на самом деле не все так страшно. При желании всему этому можно научиться за месяц👨‍💻 При условии, что вы уже 1-2 года работаете в IT, например, специалистом техподдержки или тестировщиком. Следующим постом расскажу, почему у меня были все возможности пойти на девопса, и почему я этого не сделал 🤷🏼‍♂️

Как изучать инструменты технического писателя нативно и без затрат личного времени? Один из простых способов — писать свои заметки в Markdown. Недавно я начал использовать для заметок программу Obsidian. Раньше пользовался только Notepad++ — это по сути обычный текстовик с кучей программистских возможностей и подсветкой синтаксиса разных языков программирования. Но недавно осознал, что для технического писателя это не совсем удачный инструмент. Порылся в Интернете и открыл для себя бесплатный заметник, в котором можно писать на Markdown. Есть динамический режим, в котором разметка сразу преобразуется в текст, как он будет выглядеть на веб-странице или в документе. Есть возможность подключать разные плагины для расширения функций и сохранять файлы в PDF. Недавно написал годовой отчет тимлиду в Markdown и сконвертил его в PDF-документ. Получилось интересно. Красиво структурировал текст со списками, заголовками, форматированием текста и даже добавил смайлики 👍 Думаю для новичков Obsidian идеальный вариант, чтобы начать осваивать Markdown разметку. Планирую дальше изучать этот инструмент: ⏺️подключить Git для хранения файлов заметок в едином хранилище; ⏺️попрактиковаться с шаблонами; ⏺️создать свою домашнюю базу знаний; ⏺️настроить Sphinx для сборки документов в PDF; ⏺️написать небольшой документ. В процессе буду рассказывать о новых достижениях. Для кого-то это может стать хорошим портфолио, если будете повторять за мной те же действия 🤫

Пора дать свой ответ В комментариях опроса (смотрите перыдущий пост) мне подсказали, что нужно было дать ещё один вариант «Да, частично согласен». Благодарю за обратную связь, исправлюсь 💡 Теперь про замечания редактора. В итоге, этот абзац в документе я подправил. По-моему получилось гораздо лучше чем было: После того, как клиент подписал документ, его статус изменяется в системе ЭДО. Далее оператор выгружает из системы ЭДО подписанный клиентом экземпляр документа. Если есть замечания, то оператор исправляет документ и отправляет корректировку или генерирует новый документ.

☀️ Синоптики рассказали, когда приморцы передохнут от жары Статью с таким заголовком как-то раз опубликовали в СМИ. Как видим, здесь явно прослеживается двусмысленность: приморцы передОхнут или все таки передохнУт от жары? 🤔 Но, если в новостных публикациях такое допустимо дабы привлечь побольше внимания, то в технической документации является грубейшей ошибкой. Писатель рискует тем, что читатель неверно запишет параметр в базу данных, неверно воспользуется API-методом или ещё хуже отключит систему в разгар рабочего дня. Основной способ, как не попадаться на такую ошибку — регулярно пополнять свой словарный запас технического русского языка. Как мы это делаем у себя в компании: ⚪️Читаем документы коллег. Те документы, которые прошли все этапы ревью и правок и были отгружены заказчику. ⚪️Сдаем на ревью свои документы редактору. Затем прорабатываем правки. Но не так, чтобы просто исправить по рекомендациям редактора, а вникаем, почему лучше написать именно так. ⚪️Ведем свою базу знаний в Confluence, где вписываем в таблицу «как надо» и «как не надо». Что могу посоветовать, если вы новичок и у вас нет редактора: 😍Ищите более опытных коллег и просите провести ревью ваших текстов. 😍Проверяйте по толковому словарю слова, в которых сомневаетесь. 😍Просто больше пишите. Можно не только документы, но и статьи. Тот же vc.ru или Хабр. 😍Читайте свои тексты вслух!