Чужие стандарты, которые можно использовать

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

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

Где искать?

🌟 Госуслуги — открытые гайды по интерфейсу и тексту, рекомендованные для всех государственных сервисов. Они охватывают дизайн-систему, интерфейсные паттерны и принципы написания текстов.
🔗 guides.gosuslugi.ru​
есть даже запись доклада со Стачки

🌟 Ozon — стайлгайд для технической документации. В нём описаны рекомендации по голосу и тону, структуре документации и визуальным элементам.
🔗 docs.ozon.ru/styleguide/​

🌟 Google Developer Documentation Style Guide
— классика жанра. Отличный пример того, как структурировать и писать документацию для разработчиков. Множество примеров на тему того, как упрощать описание сложных концепций.
🔗 developers.google.com/style​

🌟 The Chicago Manual of Style — один из самых авторитетных источников по вопросам стиля, грамматики и оформления текстов. Широко используется в издательском деле и научных публикациях.
🔗 chicagomanualofstyle.org​


Почему это важно?

Чужие гайды — это не просто чужой опыт. Это уже проверенные временем практики, которые можно быстро перенести в вашу команду. Почему не взять лучший опыт и не адаптировать его под себя?​

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

Что с этим делать:
- найдите подходящий гайд,
- внимательно посмотрите на него,
- адаптируйте под специфику своей работы.

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

Стачку отработали, всем спасибо! Было, как обычно, классно 😳

С Антоном работали в Ozon Tech, с Машей познакомились на прошлой Стачке и она вообще топ-звёздный спикер ⭐️

Ииии мы втроём кое-что для вас готовим 😐
Маша даже уже начинает потихоньку анонсировать, что именно

Зачем вообще стандарты, если ты не ГОСТ?

В каждой команде есть документация.
И почти в каждой — она оформлена по-разному.
Даже внутри одной команды.

Тут заголовки жирным, там курсивом.
Здесь список с точками, там — с дефисами.
Кто-то пишет «результат будет получен», кто-то — «юзер увидит кнопку».

И вроде всё работает. Но:
- новичку тяжело вникать;
- читателю — тяжело читать;
- тебе — больно поддерживать.

Ой, Катя, докапываешься до букв. Я на это даже внимания не обращаю.
Обратишь, когда увидишь хороший текст 🙈

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

Это не душно. Это удобно.
Хотя всё-таки чууууть-чууть душновато, признаю 😅
И даже если у вас нет редактора — стандарты можно собрать из ваших же лучших примеров.

Подготовила вам серию постов, будем разбираться в минимальной гигиене ⭐️

🤩 Как писать сокращения в рабочих текстах

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

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

🤩 Когда сокращение — это ок:
- слово понятно без расшифровки,
- его часто используют в команде,
- текст внутрикомандный.

🤩 Когда стоит задуматься:
- слово может быть непонятно новичку или смежнику,
- сокращение звучит двусмысленно,
- текст читает не только ваша команда.


🤩 Если термин привычный для читателя — всё ок. Такие сокращения звучат естественно, если все на одной волне.

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

Но если пишете «релизка» в документации для партнёров — лучше заменить на «описание релиза».

Хороший принцип: упрощайте для своих, но не шифруйте текст для остальных. Подумайте о тех, кто будет вашим текстом пользоваться

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

Если вы не техпис, но хотите, чтобы текст выглядел аккуратно — вот короткий чек-лист. Помогает навести порядок даже в тикетах и вики


#️⃣ How to write like a techwriter

🔴 Списки — единообразные и без пляшущего форматирования.

🔴 Скобки — по минимуму, чаще всего их можно просто выкинуть.
Ильяхов: Без скобок

🔴 Сокращения — без точек: техплатформа, архревью.

🔴 Абзацы — через пустую строку, особенно если пишете в Notion или вики.

🔴 Заголовки —используем именно заголовки, не просто жирный текст; без точек, запятых и вопросительных знаков.

🔴 Тире — длинное, а не дефис.
На маке: ⇧ + ⌥ + тире. На винде: Alt + 0151 на цифровой клавиатуре.


Следующий glow up — вычищать канцелярит:
➡️ bureau.ru

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


А аккуратный текст — это не занудство, а уважение к читателю.
А оправдывание занудства — это не душнилово 🦆

Нагенерила себе техписов 😐

Интересно, в какой вселенной они лучше работают 😅

Го в коменты ваши версии техписов от чатжпт 👇

📣 Одна горячая новость за другой

Вакансия в Крауд на мои проекты

Ищем двоих, технически грамотных, будем с вами делать доки для внутренних сервисов Райдтеха 🏠

Если откликаетесь — напишите мне в лс @ushkatia свои фио, чтобы я вас могла найти среди остальных откликов

🎨Кто выступит в секции «Техническая документация» на IT-конференции «Стачка» в Ульяновске?

→ Татьяна Тимофеева – аналитик в Ibs. Доклад: «Трудности перевода, или Как хорошо написать документацию ГОСТ»
→ Дарья Цыплакова – руководитель отдела технической документации в Nemo.Travel. Доклад: «Писать нельзя делегировать: как маленькая команда техписов живет в большом бизнесе»
→ Вера Крючкова – руководитель направления технической документации в РУСАЛ. Доклад: «Как оптимизировать систему документации в компании, если требуется и клиентов привлечь, и ГОСТам соответствовать»
→ Константин Нежберт – технический писатель в АО «Флант». Доклад: «Орфография в контейнере: CI/CD для проверки документации»

Тезисы докладов по ссылке: https://ul25.nastachku.ru/technical-documentation-ul25

Кому будет полезно: техническим писателям; специалистам из продуктовых команд: аналитикам, продактам, тестировщикам; сеньор-разработчикам.

💡Эксперт секции: Екатерина Ушакова – руководитель отдела технической документации и UX-редактуры в Ozon Tech. Лектор курса Technical Communication в Университете Иннополис.

Присоединяйтесь к «Стачке» 18-19 апреля (Ульяновск, УлГПУ). Билеты на сайте: nastachku.ru/buynow

Стачка уже через две недели и вот такую сетку мы подготовили по техдоке 🔥

Так долго и тщательно готовили, что я уже успела поменять компанию 😅

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

Напоминание перед завтрашней конфой


1. Заранее подумайте о вопросах, которые хотели задать спикерам. Не надо ходить на конфу просто послушать — для этого будут записи в х2. Список вопросов я обычно просила ещё на этапе согласования командировки, чтобы понять будет ли реальная польза от билета 😿


2. Выберите доклады, на которые точно не пойдёте. Как раз те, которые посмотрите в записи. Оцените, есть ли смысл отдельно подойти ко спикеру и познакомиться. Но если к докладу нет вопросов, просто интересненько — лучше скипайте и смотрите на х2.


3. Приготовьте ссылку на свои контакты: тгк, сайт, сетку. С людьми можно просто знакомиться. Просто подходить и говорить «Привет, я Катя, занимаюсь процессами документирования и поддержки». Даже если кроме обмена контактами ничего не произойдёт — прокачаете свой иммунитет к кринжу 🐈


4. После конференции — посмотрите на список вопросов и ответы на них. Подумайте, зачем они вам и какие шаги вы можете по ним сделать. Посмотрите доклады, которые хотели посмотреть в записи. Напишите пару постов в свой тгк с заметками с конфы 😎


#TWD2
Меня там снова не будет, делитесь фотками и впечатлениями 😽

Если у вас недостаток мотивации, держите этих двух гениев

🕺 Танец милкшейка

🕺 Педро и его airpods

now work it🎵

Всю неделю много работаю с Курсором.

Моё разочарование в разработке приобрело новые оттенки.

С внедрением ИИ прямо в IDE ты всё ещё кодишь 10% времени, а остальные 90 — дебажишь и что-то чинишь.

Ничего не поменялось, просто теперь ты делаешь это вместе с революционными технологиями.

Если вы читали пост Ильяхова про оформление ссылок, то у меня для вас есть дополнение.

Вот это: https://www.skillcup.ru/courses/ilyahov_preza_ogon?utm_source=Iliyahov&utm_medium=All&utm_campaign=Prezaogon — большая непонятная перегруженная ссылка. Её не надо использовать. Её надо адекватно оформить, чтобы люди не знали о вашей разметке источников.

Вот это: skillcup.ru/courses/ilyahov_preza_ogon — всё ещё большая и непонятная ссылка. По ней уже видно сам сайт и можно запомнить часть ilyahov_preza_ogon, но звучит это странно.

И только вот это: skillcup.ru — адекватный вид ссылки, если не смогли вписать её в текст.
Максимум: boosty.to/ushkatia — если сразу после сайта идёт алиас, название или что-то, что пишется ровно так, как оно написано в ссылке.

На Хабре вышла статья как мы в Ozon стайлгайд собирали

Читать и лайкать 💙

😱 FAQ не работают — что делать?
не делать факи

Логика появления чавошных понятная: люди задают одни и те же вопросы — давайте соберём их в FAQ.

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


Почему так?

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


Что работает лучше?

✅ Встраивать знания в работу
Автоответы в мессенджере — бот сам кидает нужную ссылку
Подсказки в интерфейсе — решение сразу в контексте задачи
Ссылки в таск-трекере — почти как подсказки в интерфейсе, но для узкого кейса

✅ Давать результат, а не текст
Вместо инструкции «Как оформить доступ» — кнопка «Запросить доступ». И дальше уже подсказки по флоу, если они нужны.
Вместо «Как назвать задачу» — автогенерация заголовка (это ещё немножко магия)

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

📌 Пользователи всегда выбирают самый быстрый способ получить ответ. Если FAQ не помогает, значит, нужен другой формат.

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

#этобаза

Очень рада за Майки и Анору — безумно понравился фильм даже после просмотра на русском.

Но я думала, что Оскар уйдёт Деми Мур.

И считаю, что победа Майки в одной номинации с Деми — буквально сюжет Субстанции 🫠

😈 Как продать команде новые процессы, чтобы они не сопротивлялись


Попытки улучшить процессы обычно заканчивается одинаково:
Зачем нам это?
Раньше было проще
и моё любимое

Очередная бюрократия, только мешает!

В итоге новые процессы либо игнорируют, либо выполняют формально, лишь бы отстали.


Как сделать так, чтобы люди приняли изменения?


✅ Решать реальную боль, а не улучшать ради улучшения

— Нельзя просто сказать: «Теперь мы пишем документацию перед задачей».
— Нужно показать: «У нас нет доки для разработки и мы тратим первую часть спринта на уточнение требований. Давайте сначала требования, потом разработка?».


✅ Показывать быстрые победы

Если ценность процесса можно почувствовать через неделю, а не через квартал, он приживётся вероятнее.

Новая форма баг-репорта? Первый же баг ушёл в работу без уточнений!
Автоматизация в Jira? Первая задача закрылась без ручного пинга!


✅ Встраивать в привычный ритм работы

Если процесс требует заполнять новую таблицу — забудьте, никто не будет этого делать.
Но если он встроен в инструмент, которым все пользуются — его скорее всего примут без боли.


Люди не против хороших процессов. Они против ненужных усложнений.

#этобаза

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

Почему внутреннюю документацию не читают
и как это исправить

📌 Главная проблема — документация существует отдельно от работы.

Люди не читают её не потому, что они плохие и ленивые, а потому что:
— проще спросить в чате, чем искать;
— инструкция не там, где её ожидают;
— текст перегружен, а ответа нет.

Как исправить?
нанять техписа

✅ Встраивать знания в процесс

В идеале документация должна появляться там, где принимается решение.
Но да, мало кто будет переделывать систему под доку.

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

хотя к шаблонам у меня особая любовь, о ней — отдельно 😅

✅ Не плодить текст ради текста

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

Поэтому:
— вместо гигантского FAQ — бот или автоподбор ответов в чате;
— вместо стены текста — структурированная стена текста и примеры.

✅ Актуализировать, когда есть реальный запрос

Бывает, что обновление документации — это задача без дедлайна.
Когда-нибудь, кто-нибудь может быть и дойдёт...

Решение:
— ловим триггеры: появился повторяющийся вопрос → обновляем инфу;
— связываем с процессами: новый релиз → автоматическое ревью документации.


Но кто всё это будет делать?

🥺 вы, если вам не хочется вечно отвечать на одни и те же вопросы.
🎧 тимлиды, если видят, что команда тратит время на поиск инфы.
💐 продукты, если саппорт завален повторами.

Документация должна экономить время. Всё остальное — бесполезный архив.

#этобаза

Пока придумываю, чего б вам тут написать и разбираюсь с новой работой — придумала вот напомнить о Стачке в Ульяновске 18-19 апреля ✨

Провели черновые прогоны, готовим доклады и о ГОСТах (!)
впервые вы о них слышите от меня, кажется, но оставляли в формах обратной связи запросы

Других анонсов у меня пока нет 😄 готова выслушать ваши идеи 🙄

А давай ты в Фигме сделаешь сразу, чтобы дизайнеру было удобно

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

Чтобы обучение было проще, можно открыть курс «Фигма для редакторов» и сразу заняться практикой. А с практикой придёт и знание инструмента, да так, что вы сможете сделать макет промостраницы и экран мобильного приложения.

Ссылка на курс→
при покупке применяйте промокод «УШАКОВА» на скидку 10% (действует до 20 февраля).

А чтобы получать бесплатные разборы работ, узнавать полезные фишки Фигмы — вступайте в Телеграм-канал.

Сейчас очень много разговариваю с коллегами о редакторах: кто это, зачем нужны, что умеют. Сама пытаюсь понять, как это в Яндексе работает, и коллегам рассказываю, какие ещё могут быть варианты. Говорим и о технических писателях, и о ux-редакторах, и в целом о текстоделах.

Вчера вот разбирали, зачем разным редакторам Figma. Не в том плане, что она не нужна, а разбирали что именно редактор делает в Figma.

Хорошо, что у меня уже была запланирована интеграция с Ильёй и можно просто сослаться на его курс 😎

Ну что, как там? Не жалеешь?

Топ-вопрос прошлой недели 🌟

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

Как там — часть посложнее 🥲

Интересно, необычно. Новые задачи, новый формат. Непривычно, что нет своей команды. Удивительно, что о некоторых вещах не задумывались и не выстраивали (хотя тогда на меня бы работы не осталось).

А вот люди — знакомые. Запрашивала доступы, а мне в ответ:

Катя, привет) готово
поздравляю с выходом =)

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


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

В среду посреди дня очень устала думать. Учитывая, что я обычно работаю из дома, смена обстановки, конечно, сильная, ещё и информации куча. Поэтому часа через 4 работы мозг просто начал отказывать. Подумала, что ну всё, остаток дня потерян.
Расстроилась.
Спустилась на этаж с джунглями, засела там на час, и удивилась как же полегчало 😱


Да, корпорации — спорная штука, но мне нравится ☀️

Привет, я Катя 💼

Из техплатформы Яндекса

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


📁 Папка с каналами про тексты
▶️ Записи Techdoc Meetup


Могу долго и развёрнуто говорить про:

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


Консультирую, менторю — просто пишите @ushkatia

а вот теперь — ухожу

Вежливо про сроки

Подслушала в офисе спор о том, как вежливо уточнить сроки.

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

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

〰️Когда сможете взять в работу? 〰️
кмк неплохо, но стоило это уточнить до формирования собственного видения сроков. Сейчас команда ответит, что в июле — что дальше будем делать?

〰️Крайний срок конец февраля — сможем уложиться?〰️
прошлый вариант плюс поинт, что срок уже крайний — что будем делать, если команда не сможет?.

Как вариант очень мягкого варианта:

Привет!
Этот проект нам нужен к концу февраля, *потому что*
Какой у вас механизм приоритезации? Что от нас надо, чтобы проект могли взять в ближайшее время?

Тут и аргументировали, и показали готовность помочь — всё по учебникам ненасильственных коммуникаций.


Но абсолютно нормальный вариант, которого не надо бояться:

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

Управление командой — это всегда игра в две стороны

Вот приходит заказчик и говорит, что им срочно, и вообще вчера, и надо прям щас всё бросить и делать 🐹

И количество таких заказчиков на единицу времени вообще не ограничено 🐹

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

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

а с другой — сразу тасовать бэклог, чтобы посмотреть а куда метеорит-то упадёт 🐹

Нередко оказывается, что действительно до начала спринта (а то и до его конца) очень даже ждёт.
А то и на пару лет зависает на холде 🐹

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

#этобаза