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

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

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

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

🕺 Педро и его airpods

now work it🎵

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


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


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


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


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


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

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

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

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

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

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

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

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

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

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

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

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

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

#️⃣ How to write like a techwriter

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

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

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

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

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

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


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

Вы тоже техпис, даже если это не прописано в должности

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


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

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

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

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

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Где искать?

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

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

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

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


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

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

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

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

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

Каждый раз когда на собесах люди упоминают наши митапы, моё сердечко тает ☺️

Но это не единственное условие к найму 😏

Если вам хочется обсудить тестовое, которое вы делали, подготовиться к собеседованию или обсудить трек развития — вы всегда можете обратиться ко мне за менторством 🫰

если вы с другой стороны и вам надо составить трек найма техписателя — такие кейсы тоже люблю и беру

🌈 Шаблон не виноват
Просто вы его неправильно использовали

Обычно шаблоны создают, чтобы всем было легче. В идеале — шаблоны снимают лишние вопросы, экономят время, помогают не забыть важное.
Но мы живём не в идеале. Поэтому вместо «проще» часто получается «ещё одна обязаловка, которую никто не читает».

🌈 Вот как бывает:

→ В команде появляются шаблоны.
→ Шаблоны заполняют как получится, потому что «так надо».
→ Никто не понимает, что с этим делать дальше.
→ Вроде документ есть, но всё равно надо спрашивать.

А потом шаблоны начинают ругать: «бюрократия!», «ничего не понятно», «шаблоны только мешают» 🌈

Но дело не в самом шаблоне, как явлении.
Дело в том, что:

🌈 шаблон не объясняет себя;
🌈 его никто не адаптирует под задачи;
🌈 он появился, потому что «все делают», а не потому что «у нас есть такая потребность».

При этом шаблон может быть классным инструментом.
Вот когда:

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

Шаблон — не скелет документа, а костяк процесса.

Он может быть удобным, умным и живым. Может помогать, а не мешать.
Но только если вы не забываете, зачем он вообще нужен.

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