🎨Кто выступит в секции «Техническая документация» на 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​


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

🐥 Анонсы

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

‼️ Strong Team IT-Conference Summer, 12 июня, Ярославль
Одна профессия, чтобы управлять ими всеми
Расскажу о профессии техписателя — что такое, кому надо, почему имба нереальная и всем рекомендую

🍿 Saint TeamLead Conf, 26 июня, Питер
Круглый стол «Индивидуальный план развития: взгляд с разных сторон»
Тут заруба ожидается жёсткая, потому что ведущий круглого стола разочаровался в ипр'ах — будем обсуждать со стороны компании, сотрудника и противника

☕️ Как сделать шаблон, который будут любить

Хороший шаблон — как хороший собеседник: подсказывает, помогает, но не лезет со своим уставом.
Посмотрим на примере постановки задачи.

⭐️ Подсказывает, а не диктует
В шаблоне не должно быть ощущения “тут надо угадать, что имел в виду автор”.

Плохо:
> «Описание задачи»
Хорошо:
> «Что случилось? В чём боль? Что пользователь не может сделать?»

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

👻 Объясняет себя
Если человек заполняет шаблон в первый раз — он должен понимать, зачем вообще всё это.

Можно прямо написать в начале:
> «Этот шаблон нужен, чтобы не забыть важное при постановке задачи на документацию. Вопросы можно скипнуть, если не релевантно».

🔄 Обновляется
Хуже шаблона может быть только старый шаблон. В который все продолжают писать, потому что «так заведено».

✏️ Собирает фидбек
Простой вопрос раз в квартал: «Что в шаблоне бесит?» — и, может быть, вы даже узнаете, зачем его вообще читают.


Хочешь универсальный шаблон шаблона?
Лови:

📌 Что произошло?  
– Опиши проблему, которую надо решить.  

🎯 Какая цель у документа/текста?  
– Что должно измениться после его прочтения?  

👥 Кто целевая аудитория?  
– Внутренние сотрудники? Пользователи? Техподдержка?

⚙️ Контексты и ограничения  
– Где будет жить этот текст? Какие ограничения в формате или времени?

📞 Кто поможет разобраться, если будут вопросы?  
– Напиши контакты держателя знания или команды.

⚡️ Гайд по объяснению пользы документации
или что сказать, когда спросят «зачем вообще это писать?»

Иногда кажется, что ты и так всё рассказал. И даже дважды.
Но потом кто-то говорит:
— Ну мы ж и так понимаем, зачем писать документацию…
— …чтобы была.
🫠🫠🫠

Вот короткий гайд, что можно отвечать:

📍 «Документация снижает количество повторных вопросов»
Если к тебе три раза подряд приходят с одинаковым вопросом — текст на эту тему может сэкономить всем время. Особенно твоё.

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

🗝 «Помогает онбордить новых сотрудников»
Хорошо написанный гайд быстрее отвечает на вопрос «с чего начать?», чем любые welcome-созвоны.

☯️ «Поддерживает процессы»
Если договориться, что всё проходит по инструкции, не надо каждый раз решать «а как на этот раз?».

🎱 «Дает точку отсчёта для анализа»
Что мы обещали клиенту? Где фиксировали процесс? Чем текущее поведение отличается от запланированного?


И, конечно:

💎 документация не просто хранит информацию, а помогает передавать её

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

#этобаза

👇 Психология восприятия технических текстов
документация создаётся для читателя, а не для автора

Одна из основных ошибок при создании документации — проецирование собственного знания на читателя. Этот феномен описывается в психологии как проклятие знания (curse of knowledge) — когнитивное искажение, при котором человеку трудно представить, каково это — не знать того, что ему известно.

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

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

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

0⃣ Когнитивная нагрузка: три компонента

Теория когнитивной нагрузки (Sweller, 1988) выделяет три основных типа ментальной нагрузки, возникающей при обучении или восприятии новой информации:

🟡Внутренняя (intrinsic load) — определяется природной сложностью самого материала.
🟡Внешняя (extraneous load) — обусловлена способом подачи информации: структурой, форматом, визуальными шумами.
🟡Продуктивная или связанная (germane load) — усилия, направленные на построение устойчивых когнитивных схем и интеграцию нового знания.

Если суммарная нагрузка превышает возможности рабочей памяти (Miller, 1956; Baddeley & Hitch, 1974), восприятие текста нарушается: читатель испытывает трудности в удержании смысловых блоков и теряет нить повествования.

1️⃣ Как проектировать документацию с учётом когнитивных ограничений

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

1. Чанкинг: группировка информации в компактные логические блоки (3–5 элементов). Это снижает нагрузку на рабочую память и помогает лучше запомнить информацию (G. A. Miller, 1956).

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

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

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

2️⃣ Как оценить понятность документации

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

🧱 Структура документации: принцип перевёрнутой пирамиды

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

⛓ Об общего — к частному

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

👍 Верхушка пирамиды — самое важное

Сюда попадает то, что должен знать абсолютно каждый читатель:
- Что это такое — простыми словами
- Зачем нужно — какие проблемы решает
- Для кого предназначено — кто целевой пользователь
- В чём главная ценность — почему стоит использовать

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

Тест верхушки: Человек, прочитавший только первый экран текста, должен понимать, стоит ли ему читать дальше.

✌️ Середина пирамиды — контекст и принципы

Если читатель остался, ему нужно понять, как это работает в общих чертах:
- Архитектура системы
- Основные сценарии использования
- Ключевые концепции и компоненты
- Взаимодействие элементов

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

Тест середины: После прочтения этой части читатель должен уметь объяснить другому человеку, как это работает, даже если ещё не знает, как этим пользоваться.

🖖 Нижний слой — детали и инструкции

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

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

Тест нижнего слоя: Читатель должен легко находить ответ на конкретный вопрос через поиск или навигацию.


👜 Как это влияет на структуру документа?

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


🦖 Почему это жизненно важно

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

Пирамида — это не только стиль. Это проявление уважения к читателю.

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


———
🪲 Проверьте свою документацию:

- Первый абзац отвечает на вопрос что это и зачем?
- Можно ли понять основную идею за 30 секунд?
- Детали появляются только после объяснения концепций?
- Читатель видит общую картину до погружения в нюансы?

Если хотя бы на один вопрос ответ «нет» — пора перестраивать пирамиду.

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

🌈 Кому мы вообще это пишем?

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

Один документ — не для всех

Частая ошибка: написать «одну универсальную статью» для всех. В итоге получаем предсказуемый результат:
- Новичкам слишком сложно
- Опытным пользователям скучно
- Поддержке не хватает деталей

Разные люди приходят в документацию с разными задачами и ожиданиями. И каждому нужно своё.

Типичные аудитории технической документации

🌈 Новички
- Ищут базовые объяснения и пошаговые гайды
- Нуждаются в контексте и обосновании («почему это важно»)
- Ценят простые метафоры и наглядные примеры
- Часто читают документацию линейно, от начала до конца

🌈 Опытные пользователи
- Используют документацию как справочник
- Им нужно быстро найти конкретное решение
- Ценят точность и лаконичность
- Примеры кода для них — скорее подстраховка, чем обязательный элемент

🌈 Интеграторы
- Фокусируются на взаимодействии между системами
- Изучают API, архитектурные схемы, процессы авторизации
- Интересуются граничными случаями и нестандартными сценариями
- Ищут детальные спецификации и ограничения

🌈 Техническая поддержка
- Им важно понять, почему система сломалась и как это исправить
- Нуждаются в описании ошибок, кодов и методов диагностики
- Ценят раздел с обходными решениями (workarounds)
- Часто используют документацию во время общения с клиентом

Как определить, для кого вы пишете?

Не нужно проводить масштабное UX-исследование. Достаточно задать себе несколько вопросов перед началом работы:

1. Этот материал будет читать новичок или опытный пользователь?
2. Читатель пришел разобраться в теме или быстро решить конкретную проблему?
3. Документ будут читать индивидуально или обсуждать в команде?
4. Сколько времени готов потратить читатель — 3 минуты или 3 часа?

Ответы на эти вопросы напрямую влияют на:
- Структуру и объем текста
- Выбор терминологии
- Глубину объяснений
- Формат подачи материала (статья vs справка)


Практический пример: оптимизация индексов в базе данных

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

🪿 Для опытного разработчика
«Составной индекс по полям (client_id, created_at) ускорит выборку в запросах с условиями по обоим полям, но увеличит нагрузку при вставке новых записей. Перед добавлением оцените баланс между частотой чтения и записи в таблицу. Для таблиц с высокой нагрузкой на запись рассмотрите возможность асинхронного создания индексов.»

🕷 Для интегратора
«При проектировании схемы взаимодействия учитывайте, что запросы к индексированным полям из внешних систем могут использовать кэширование на уровне БД. Убедитесь, что ваш API корректно передает параметры сортировки, соответствующие структуре индексов, особенно для составных индексов.»

🐝 Для техподдержки
«Если клиент сообщает о замедлении запросов после обновления, проверьте состояние индексов через SHOW INDEX FROM table_name. Фрагментация выше 30% может требовать перестроения индекса. Для временного решения без перестроения можно использовать FORCE INDEX в критичных запросах.»

Каждый раз, когда садитесь писать технический текст, спросите себя: кому я сейчас это объясняю?

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