Привет!

Итак, новая рубрика Вопрос-ответ. Представим, что кто-то задал мне вопрос:

Нужна ли вежливость в инструкциях? Если да, то в каком объёме?

Что ж, отвечаю:

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

Здороваться, извиняться за потраченное время, целоваться при прощании не стоит. Пользователь хочет поскорее решить свою проблему, поэтому наша цель — предоставить ему рабочее решение.

Я взял за правило обращаться к пользователю на «вы» (без прописной буквы, разумеется!), использовать определённо-личные предложения и повелительное наклонение глаголов:

Пройдите по ссылке, нажмите кнопку, заполните поле.

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

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

Для «пожалуйста» работает простое правило: если действие, которое должен выполнить пользователь, нужно нам, а не ему, мы сопровождаем такое действие просьбой. Например, мы хотим, чтобы пользователь оставил обратную связь, разрешил использовать куки, подписался на дайджест техподдержки. Ему от этого ни тепло, ни холодно, а нам очень даже тепло — поэтому мы вежливо просим: «Пожалуйста, оставьте обратную связь», «Пожалуйста, разрешите куки», «Пожалуйста, подпишитесь на нашу рассылку».
Рутинные же действия инструкции пользователь выполняет в своих интересах, поэтому мы декларируем, что именно он должен сделать, чтобы решить свою проблему, и «пожалуйста» тут не требуется.

Надеюсь, я ответил достаточно развёрнуто)) Задавайте свои вопросы в чате Pararwriter REVIEW, я постараюсь ответить на все, а самые интересные буду публиковать на канале в рамках рубрики #вопрос_ответ

Пожалуйста, ставьте реакции на пост, оставляйте комментарии 🙃

Беспощадный UX возвращается.

Дано: детский парк, стенд с правилами поведения на карусели. Среди прочего такой интересный знак.

Вопрос (напрашивается сам собой): что этот знак запрещает? Я сломал голову (как человечек на знаке), но так и не смог разобраться.

Пишите ваши предположения и варианты в комментарии, буду рад понять, что это означает)

#ux

Всем привет, меня зовут Антон, и я вайб-кодер 🫣 (аплодисменты, слова поддержки).

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

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

Но в какой-то момент и сторонних плагинов становится мало. Остаётся один выход — написать новые плагины самому. Раньше на этом этапе я вспоминал, что я не программист, и грустно вздыхал.

Однажды я подумал: почему бы не попросить искусственный интеллект написать нужный мне код? И попросил) А он взял и написал.
Правда, ничего не заработало 😁

Спустя пару часов увлекательного общения со скайнетом наконец-то получилось добиться работающего расширения для моего сайта.

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

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

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

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

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

#практика

Лето — это не только бесконечные отпуска, копание в огородах и шашлык по воскресеньям.
Лето — это прекрасное время для прокачки профессиональных навыков.

Ура, 25 августа в Москве состоится конференция про контент в IT — WriteConf.

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

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

Посмотреть программу, узнать подробности, зарегистрироваться и купить онлайн или оффлайн билет можно на сайте.

#карьера

Думаю, по вчерашнему посту (особенно по его первой итерации) вы уже догадались, кто стал партнёром конференции WriteConf 🫣

В честь этого мы вместе с организаторами решили разыграть один оффлайн-билет!

Всё просто:
1. Подпишитесь на канал конфы.
2. Оставьте любой комментарий под этим постом.

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

Жду ваши комменты до конца этой недели, итоги подведём в понедельник, 21 июля.

Желаю всем удачи! Пусть вам повезёт ❤️

Привет!

Уже завтра мы разыграем один оффлайн-билет на конференцию WriteConf, которая пройдёт 25 августа в Москве.

Вы ещё можете принять участие: подпишитесь на канал конфы и оставьте любой комментарий под конкурсным постом на парарайтере сегодня, 20 июля, до 23:59 по МСК.

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

И желаю всем удачи завтра! 🕊

Друзья!

Вот и настал торжественный момент — мы провели розыгрыш и узнали, кому достанется оффлайн-билет на конференцию WriteConf!

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

Розыгрыш состоялся сегодня, 21 июля 2025 года в 12:53.

Победителем стал подписчик с ником @mmmstasia! И да, прошу прощения, я как всегда неправильно прочитал ник на записи))

Друзья! Для всех, кто принял участие в конкурсе, мы подготовили утешительный приз — промокод на 10% скидку при покупке оффлайн-билета. Напишите мне в личные сообщения, и я вам его вышлю с первым почтовым голубем 🕊

Ещё раз поздравляю победителя! Хорошей всем рабочей недели!

Привет!

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

Хотите размять мозг и немного подумать? Тогда у меня есть кое-что для вас) И это кое-что — детский сканворд, над которым я как следует поломал голову.

Самостоятельно у меня получилось разгадать только птицу, а потом я не выдержал и посмотрел ответы 🤪

Надеюсь, у вас получится лучше, чем у меня) Пишите ваши догадки в комментарии!

#флуд

Чем внутренняя документация отличается от внешней?

Глобально ничем. Любой технический текст должен быть:

- понятным;
- согласованным (консистентным);
- полезным для целевой аудитории;
- минимально избыточным.

Это база, высеченная на путевом камне при входе в профессию тех.писателя)

Но всё-таки между внутренней и внешней докой есть одно различие.

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

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

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

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

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

А что об этом думаете вы? Поделитесь своим опытом в комментах, будет интересно обсудить)

#практика

Привет!

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

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

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

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

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

2. Символы с английской раскладки
Я работаю с маркдауном, поэтому часто пользуюсь квадратными и фигурными скобками, обратным апострофом (бэктиком), одинарными кавычками, разными слэшами. А также собачкой, амперсандом, решёткой и даже иногда знаком доллара 🤑. Все эти символы я поместил в свою раскладку, установив их на их родные английские клавиши.

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

Как это работает?

Работает это всё очень просто: дополнительные символы набираются с помощью двух типов комбинаций: AltGr+клавиша и AltGr+Shift+клавиша. Я постарался сделать все комбинации удобными для набора, большую часть можно зажать пальцами одной руки.

Обновление раскладки

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

Так что правки всего две:

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

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

А можно мне?

Ну конечно!) Единственное, пока раскладку можно использовать только на устройствах с Windows, но если будет устойчивый спрос, я попробую адаптировать раскладку и для других систем).
Установочные файлы, инструкция и схемы-подсказки лежат на GitHub (да-да, у нас всё по-взрослому): https://github.com/novillero/tech-layout

Скачивайте, устанавливайте себе на комп, пользуйтесь и приходите с обратной связью: можно сюда на канал, а можно в issues в репозитории проекта.

P.S. Участвую в конкурсе «Продолжи мысль» от @systems_education
#продолжи_мысль_SE #практика

Какой самый сложный вопрос вам приходилось решать на работе?

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

Самой сложной задачкой, задачкой порой почти неразрешимой для меня оказался простой вопрос:

Как понять, что писать нужно, а что писать не нужно? И где найти мудрость всегда отличать первое от второго?

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

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

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

Оптимального рецепта, как быть в такой ситуации, у меня нет. Но есть несколько советов, которые могут помочь:

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

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

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

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

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

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

7. Не отчаивайтесь! Когда-нибудь вы окажетесь в лучших условиях, и, вполне вероятно, вам придётся создать их для себя самостоятельно)))

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

#практика

Вот и ещё одна рабочая неделя позади, с чем вас и поздравляю!

Сегодня пришли результаты первого тура конкурса авторских публикаций «Продолжи мысль» от Systems Education. Два поста парарайтера прошли во второй тур, это ли не прекрасная новость?)

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

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

И хороших выходных, конечно же)

#карьера #практика

Привет!

Часто мы обсуждали здесь разные технические штуки: апи, sql, docs as code и много чего ещё.

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

Сегодня я хотел бы поговорить об одном из таких мягких навыков — умении получить нужную информацию из нужного человека.

Спрячьте утюги и паяльники, бросьте писать письма с угрозами — мы попробуем обойтись разрешёнными и законными методами опроса)

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

Как правильно выстроить взаимоотношения так, чтобы не отфуболивали при первом же приближении с «дурацкими вопросами»?

В первую очередь я предлагаю загрузить базовые установки:

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

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

3. Отвечать на мои вопросы — это часть работы моих коллег, за которую они получают деньги.

4. Я не отнимаю личное время коллег, мы вместе тратим наш общий ресурс — наше рабочее время.

Загрузили? Отлично. Теперь переходим к практическим советам:

1. Подготовка опроса — 50% успеха.

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

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

2. Разговор удобнее переписки.

По возможности я стараюсь встретиться с человеком, поэтому пишу что-то типа такого:

Привет! Я занимаюсь описанием такой-то фичи, ты мог бы мне помочь уточнить пару моментов по реализации? Я предлагаю созвониться минут на 15, тебе будет удобно завтра, в 12:30? Если нет, подскажи, пожалуйста, в какое время будет комфортнее, я закину встречу.

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

3. Не отвечать — это нормально.

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

Я обычно пользуюсь такой схемой:

Если задача несрочная ↓

сообщение в личке → ёще одно сообщение в личке на следующий день → ёще одно сообщение в личке через несколько часов → снова сообщение в личке на следующий день → эскалация на руководителя

Если задача срочная ↓ 

сообщение в личке → ещё одно сообщение в личке через 2 часа → эскалация на руководителя

Как правило, хватает первых двух шагов)

4. Будьте вежливы и дружелюбны.

Чувак не отвечает уже неделю? Это не повод менять тон ваших сообщений на более жёсткий. Вежливость — оружие королей и техписателей.

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

5. Не бойтесь задавать глупые вопросы.

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

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

А как вы общаетесь с держателями знаний? Расскажите о своём удачном и неудачном опыте в комментариях, будет интересно)

У меня кстати был неудачный опыт! Поделюсь в комментах 😱

#практика #софты

Привет!

Вчера я пережил неописуемый пользовательский опыт. Это точно заслуживает рубрики Наибеспощаднейший ux.

Итак, прилавок с конфетами в магазине. Висят ценники с надписью «Один цвет — одна цена».

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

Ладно, пусть так, но должен же быть ещё какой-то смысл единой цены для разных конфет?

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

Но не тут то было! На кассе продавцы расфасовывают собранные покупателями пакетики и рассортировывают конфеты обратно, чтобы пробить по отдельности. Как я понял, происходит это регулярно))

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

Хотя, может, это я туго соображаю, и всё очевидно?

Давайте решим вместе, прав я или нет: голосуйте в опросе ниже, посмотрим, кто победит)

#ux

Привет!

Девиз «Пиши! Сокращай!» знают уже наверное все в нашей профессии. Казалось бы, стоит ли снова поднимать тему о том, как писать легко и непринуждённо?

Стоит! Ведь коварный канцелярит прекрасно адаптируется и мимикрирует под доброкачественную речь. Поэтому давайте попробуем дать ему ещё один бой.

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

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

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

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

Как же вычислить этот коварный канцелярский штамп?

Совсем несложно. Этот коварный штамп строится по шаблону совершать/совершить [какое-то] действие: проводить работу, выполнять анализ, участвовать в выступлении. Если такое словосочетание можно без потери смысла заменить простым глаголом действия, то перед вами штамп: проводить работу = работать, выполнять анализ = анализировать, участвовать в выступлении = выступать.

Если конструкцию не получается заменить глаголом, то перед вами не штамп: например, «составлять план» и «планировать» часто подразумевают разные действия.

Казалось бы, ну такой безобидный штампик, ну пусть он остаётся в нашей речи! А вот и нет! Это он только на вид такой безобидный. Посмотрите, как в первом моём примере простое действие проанализировать разложилось на три (провести работу по анализу). Канцелярит опасен тем, что притягивает к себе другой канцелярит. Фразы становятся тяжелее, неповоротливые конструкции из причастий и отглагольных существительных нанизываются друг на дружку и превращают ваш текст в монструозное нечитаемое нечто.

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

#практика

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

Но унификация не победила авторскую идентичность.

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

Дальше — больше. Теперь, когда ко мне на ревью попадает текст, я понимаю, кто именно из моих коллег его написал. Правда, мои коллеги не технические писатели, а разработчики, аналитики и девопсы, менее искушённые инфостилем, поэтому вычислить их гораздо легче)

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

А вам удаётся сохранить свой стиль в документации? Поделитесь своим опытом в комментариях, будет интересно обсудить)

#флуд

И ещё раз о софтах

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

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

Поэтому я стараюсь всегда оставаться:

– дружелюбным
– в меру вежливым
– готовым помочь

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

Не хватает настойчивости.

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

Однако, настойчивое дружелюбие предполагает соблюдение некоторых правил:

1. Никаких конфликтов.
2. Никакой токсичности в общении.
3. При необходимости только мягкая эскалация (в духе: «пожалуйста, помоги обратить внимание Игоря на такую-то задачу, она срочная, а её решение затягивается»).

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

Кстати, настойчивым дружелюбием можно пользоваться и в рутинной повседневности — попробуйте, не пожалеете)

#практика #софты

Вчера сходил на конференцию Doc Config от Сбертеха.

Много говорили о работе с нейросетями. Я всегда сомневался в своих методах взаимодействия с ИИ, но оказалось, что все делают также, как я))

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

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

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

В общем, спасибо Platform V от Сбертеха за крутое и вдохновляющее мероприятие. Рекомендую ходить на митапы (или слушать их онлайн, как обычно делаю я), это весело и познавательно)

#карьера