Когда размеренно работал над доком, но потом настало демо...

Недавно наткнулся на исследование про влияние ИИ на критическое мышление работников:

https://www.microsoft.com/en-us/research/wp-content/uploads/2025/01/lee_2025_ai_critical_thinking_survey.pdf

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

Моё мнение - стараться максимально адаптироваться и использовать все возможности ИИ, потому что в перспективе придется либо терять работу, либо учиться работать совместно с ИИ.

Но не забывать о том, что раньше, чтобы решить задачу, нужно было не думать над промтом, ответ на который выдаст решение, а (о боже вот это инсайт) над решением задачи😁

А вы что думаете?

Этим летом компания YADRO проводит стажировку по разработке технической документации!

Всем заинтересованным 👇

Открыта регистрация на летнюю оплачиваемую стажировку YADRO Импульс по 40+ направлениям, одно из них - разработка технической документации.

💡ВЫ БУДЕТЕ ВЫПОЛНЯТЬ ОДНУ ИЗ ЗАДАЧ:
1. Создавать документацию на серверы и системы хранения данных для администраторов ЦОД, разработчиков интеграционных решений и других «продвинутых» пользователей.

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

3. Разрабатывать инструкции для специалистов собственного производства.

🥇ТРЕБУЕМЫЕ ЗНАНИЯ И НАВЫКИ:

Обязательные:
-Грамотность и знание принципов построения структурированных текстов
-Любознательность и готовность погружаться в новые предметные области
-Коммуникабельность и умение формулировать вопросы так, чтобы получать на них ответы

Будет плюсом:
-Опыт работы с системами контроля версий
-Опыт работы с языками разметки
-Технический бэкграунд

ЧТО ТЕБЯ ЖДЕТ?
⏺️С первых дней — работа над реальными проектами
⏺️Наставник, который поможет в решении задач и адаптации
⏺️Оплачиваемая стажировка (40 часов в неделю)
⏺️Образовательная программа от экспертов YADRO
⏺️Возможность получить оффер и остаться в компании

📆Когда? 7 июля — 29 августа
📍Где? В офисе или удаленно

🔊Подать заявку можно до 27 апреля на сайте

Как мы будем внедрять docs as code у себя в компании? Делюсь нашим стеком инструментов:

 🔹Git — для хранения всей документации, управления версиями и совместной работы через pull request'ы.
🔹 Visual Studio Code (VS Code) — чтобы писать и редактировать документы в Markdown в удобной и быстрой среде.
🔹 Docker — чтобы без лишней настройки запускать рабочую среду.
🔹 Docusaurus — чтобы собирать всю документацию в аккуратный и удобный для пользователей сайт.

Как будет выглядеть сам процесс работы:

1. В VS Code мы пишем или редактируем документацию в формате Markdown.

2. Все файлы документации сохраняются в репозитории на Git — там создаются ветки, туда отправляются изменения и проводится ревью.

3. Чтобы увидеть, как сайт с нашим текстом будет выглядеть, мы запускаем Docker — он без лишних установок поднимает среду с Docusaurus, и тот собирает Markdown-файлы в красивый статичный сайт.

5. После проверки изменения отправляются в основную ветку Git, и сайт обновляется при следующем деплое.

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

Полезные ссылки на Хабр для ознакомления:
- Git
- Visual Studio
- Docker

Интересный пост от техрайтера с опытом про то, как справляться с выгоранием на работе:

https://habr.com/ru/companies/x5digital/articles/908634/

Настройка стиля пользовательской документации

Когда создаешь пользовательские инструкции, важно не только что пишешь, но и как.

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

Вот несколько простых, но важных правил, которые мы стараемся учитывать:

🔹 Минимум обращений к пользователю.
Вместо: "You will see a list of records..."
Лучше: "The tab displays a list of records..."
Это делает текст нейтральным и сфокусированным на действии, а не на читателе.

🔹 Императив — наш друг.
Вместо: "When you log in, you'll land on the Dashboard page."
Лучше: "Log in to open the Dashboard."
Такой стиль короче, яснее и лучше подходит для инструкций.

🔹 Без вводных фраз, которые не несут смысловой нагрузки.
Фразы вроде "So,", "Let’s see", "Just a quick note" — могут работать в блогах, но в инструкциях они только загромождают текст.

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

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

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

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

В какой-то момент таблички в лифтах, UX-сообщения и подписи на кнопках превращаются в стилистический анализ — только в дикой природе.

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

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

Где-то там идут трудовые будни, задачи двигаются и решаются, коллеги что-то спрашивают… Но ты просто краем глаза смотришь на экран — и внутри тихая радость: Отвечать не нужно! Можно просто выдохнуть и с улыбкой закрыть телефон.

А вот возвращение — это особый ритуал. Первая половина дня после отпуска уходит не на работу, а на разгребание накопившегося:

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

Такое чувство, будто ты не просто вернулся, а пробираешься сквозь цифровую заросль, чтобы снова выйти на тропу дел 😁

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

Пунктуация в туллтипах

Если вы не пишете по ГОСТу, то всё упирается в внутренние правила и здравый смысл. В идеале, конечно, ещё и в согласованное чувство стиля внутри команды👨‍💻

Ориентироваться можно на подход крупных IT компаний, которые уже сформировали свои гайдлайны, где тон, структура и пунктуация UI-текстов продуманы до мелочей. Но полностью копировать — не всегда хорошая идея: важно учитывать специфику продукта и требования вашего руководства.

Мы, например, в туллтипах приняли такие правила:

— ставить точку в конце, если текст это полноценное предложение (содержит подлежащее и сказуемое), или если туллтип содержит два и более предложений

— если же это короткий фрагмент вроде «Shows monthly summary», то используем его без точки

А если туллтип описывает сложную метрику и превращается в мини-объяснение с числовыми значениями в буллетах, то мы делаем так:

По ховеру на метрику, например, System Performance, возникает вот такой туллтип:

In the Trailing Year:
– Deployments – 280
– Rollbacks – 19
– Uptime – 99.89%
– Incidents reported – 11
– Avg. response time – 310 ms

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

https://naked-science.ru/community/1100328

Доживаем свой век, дамы и господа писатели 🫡

Наткнулся тут на подходящий напиток для техпитателей😁

🚀 27-28 марта 2026г. в Москве пройдет TechWriter Days 3 — международная конференция для технических писателей. Мероприятие состоится в гибридном формате — офлайн + онлайн-трансляция.

Вас ждут 60+докладов и мастер-классов, 2 дня профессионального общения с 400+ участниками из сотен компаний СНГ, полезные инсайты и новые знания!

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

Будем ждать всех на TechWriter Days 3🙏🏼

⚡️билеты
⚡️афиша
⚡️скидки
⚡️видео

3 UX-мелочи Jira, которые бесят меня как юзера и техписателя

1️⃣ Скроллбар-невидимка
В списке статусов иногда по какой-то причине нет заметного скролла. Чтобы добраться до Done или On prod нужно догадаться, что окно вообще можно прокрутить вниз. Мелочь, но порой подбешивает.

2️⃣ Пляшущие таблицы в комментариях
Если вставить таблицу в коммент к тикету, то при редактировании она начинает разъезжаться и постоянно скачет. А если комментарий длинный, то сам редактор сходит с ума: автоскролл скачет, курсор уезжает, ввод тормозит. В итоге даже простая задачка превращается в испытание на терпение.

3️⃣ Кастомизация вместо универсального удобства
Jira, конечно, инструмент мощный, но по умолчанию многое сделано так себе. Чтобы настроить рабочее пространство под себя, придется потратить уйму времени на кастомизацию. Гибкость высокая, но комфортной работы не дает.

📌 Для техписателя это особенно заметно: интерфейс должен быть предсказуемым, чтобы инструкции были четкие и совпадали с опытом пользователя. Но Jira часто превращает простые действия в мини-квесты.

Даже не представляю как бы я описал все use cases если бы пришлось делать инструкцию по джире😂

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

Но есть и еще одна достаточно важная составляющая такой работы.

Барабанная дробь...

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

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

В своем уютном телеграм канале она с юмором и большой любовью рассказывает про английский язык. Вот некоторые интересные посты:

- Рассказ про English Speaking Club
- Как проходить собеседования на английском
- Про слова-гибриды

А вот здесь выложен дайджест самого интересного на ее канале.

В общем, ребята, если планировали начать или продолжать учить английский - рекомендую написать Марии (@MaryArcher312) и проконсультироваться. Дерзайте😊

Техрайтеры, когда с ними не согласовали тексты для нового UI, а они тем временем невозмутимо катятся на прод

Ребята, предлагаю вам информацию по стажировке SafeBoard по Technical Writing ⛵️

Осенняя стажировка в Kaspersky по Technical Writing — это выход в открытое море задач. Вы разберетесь в сложных технических темах и научитесь превращать их в понятные инструкции 🧑‍💻

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

Что будет на стажировке:
✅ Полное погружение в процессы создания IT-продуктов
✅ Работу над реальными задачами, влияющими на миллионы пользователей
✅ Наставничество от опытных технических писателей

Прием заявок: с 26 августа по 15 сентября.

Оффер на горизонте — держи курс на стажировку! Регистрируйся сейчас: https://kas.pr/9spx

Техрайтер, когда у него перестал работать впн, который день лагает интернет, давит дедлайн по проекту, на носу performance review, а в доме еще потек потолок, но он старается не терять бодрости духа и оптимизма

Теперь обрабатываем скриншоты в Figma

Мы продолжаем совершенствовать наш подход к документации в стиле docs as code 🧑‍💻

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

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

Пока, конечно, непривычно и тратится много времени, но как говорится век живи, век учись!

Так документация становится не только понятной, но и визуально цельной и консистентной.

Если docs as code это про системность и качество, то те же принципы теперь работают и для изображений.

Качественные тексты и красивые скрины теперь будут идти в комплекте 😁