Список книг больше не работает как учебный план
Десять лет назад новичку можно было дать несколько книг о техническом письме, добавить руководство по инструменту и получить неплохую программу на несколько месяцев. В 2026 году такой список слишком быстро превращается в музей. Интерфейсы меняются, генеративный ИИ переписывает часть редакционного процесса, Git и автоматические проверки входят в обычную работу, а публичные style guides крупных технических компаний обновляются быстрее бумажных изданий.
Книги при этом не стали бесполезными. Книга хорошо разворачивает длинную мысль: как думать об аудитории, качестве, структуре и организации команды. Живой онлайн-гайд лучше отвечает на другой вопрос: как сегодня оформлять команду, heading, code sample, UI label, термин или procedure. Нормальная учебная программа использует оба типа источников и не пытается выбрать один «главный».
По состоянию на август 2026 года Microsoft Writing Style Guide и Google developer documentation style guide продолжают получать обновления; GitHub публично описывает собственные content models и принципы Docs; IBM держит открытые Content Standards; Diátaxis развивается как практическая система для разделения tutorial, how-to, reference и explanation. Сопоставление живых руководств полезнее списка «пять лучших книг», потому что позволяет увидеть разные школы на одной задаче.
Пять живых гайдов, которые стоит держать открытыми
| Источник | Сильная сторона | Конкретное правило или модель | Когда открывать |
|---|---|---|---|
| Microsoft Writing Style Guide | Голос, процедуры, UI, терминология | Пишите проще, ведите читателя к действию, используйте активный залог и прямые команды в procedure | Когда текст тяжёлый, формальный или перегружен канцеляритом |
| Google developer documentation style guide | Developer docs, глобальная аудитория, code style, headings | Ставьте условие до инструкции, обращайтесь к читателю напрямую, оформляйте code entities как code | Когда пишете API, CLI, cloud/dev docs или готовите текст к локализации |
| GitHub Docs style и content model | Пользовательская задача, структура статьи, сканирование | Сначала цель пользователя, затем только необходимый контент; отдельные модели для concept, how-to, tutorial, troubleshooting, reference | Когда статья разрастается и непонятно, что в ней вообще должно остаться |
| IBM Content Standards | Системная оценка качества | Проверяйте task orientation, accuracy, completeness, clarity, organization и retrievability как разные свойства | Когда нужно не «понравился текст / не понравился», а полноценное редакционное ревью |
| Diátaxis | Архитектура и типы документации | Не смешивайте tutorial, how-to, reference и explanation в один бесконечный материал | Когда справочник превращается в учебник, а tutorial — в энциклопедию |
Разница между этими источниками полезна. Microsoft и Google часто помогают решить проблему на уровне предложения и процедуры. GitHub поднимается на уровень content design. IBM предлагает язык для оценки качества целого информационного продукта. Diátaxis помогает решить, какой тип материала вообще нужен читателю. Один гайд не заменяет остальные.
Сравним одну и ту же проблему в разных традициях
Возьмём плохую фразу из условной инструкции:
Для того чтобы успешно завершить операцию, пользователи должны убедиться, что репозиторий был предварительно инициализирован, после чего следует нажать кнопку Create.
Microsoft-подход тянет фразу к короткой инструкции с явным действием:
Инициализируйте репозиторий, затем выберите
Create.
Google отдельно обращает внимание на условия перед инструкцией. Если инициализация — prerequisite, порядок можно сделать ещё яснее:
Перед тем как выбрать
Create, инициализируйте репозиторий.
GitHub заставляет задать другой вопрос: зачем читатель вообще выполняет шаг? Если цель — создать проект, полезнее дать контекст раньше детали:
Чтобы создать проект, инициализируйте репозиторий, затем выберите
Create.
IBM-подход не заканчивается переписыванием предложения. Редактор проверит, действительно ли инициализация обязательна, понятен ли термин «репозиторий», хватает ли prerequisite и указан ли результат действия. Красивая фраза с неверным prerequisite по модели IBM остаётся плохой документацией.
Diátaxis может вообще удалить предложение с этой страницы. В reference описывают параметры и поведение системы; пошаговая инструкция относится к how-to. Одно редакционное решение иногда полезнее десяти улучшений стиля.
Та же логика работает с заголовком «Работа с репозиториями». Для concept page такой заголовок ещё может обозначать тему, но для процедуры лучше «Создайте репозиторий» или «Настройте доступ к репозиторию». Название сразу сообщает задачу и не заставляет читателя угадывать содержание раздела.
Изучайте одну проблему за раз — но с конкретным заданием
Фраза «изучайте task design» ничего не даёт, пока рядом нет упражнения. Учебная тема должна заканчиваться артефактом, который можно положить рядом с исходником и сравнить.
| Проблема в реальной документации | Что открыть | Что сделать за 60–90 минут | Что останется после упражнения |
|---|---|---|---|
| Procedure начинается без prerequisites | Microsoft procedures + Google guidance для instructions | Возьмите одну реальную процедуру, вынесите условия до шагов, сократите вводный текст, добавьте ожидаемый результат | Версия before/after и правило для локального style guide |
| API reference содержит три экрана объяснений перед полями | Diátaxis Reference + Google code samples | Отделите факты endpoint от сценария использования, оставьте короткий пример request/response | Чистая reference page и отдельный кандидат на how-to |
Команда пишет sign in, login, log in как придётся |
Google word list + Microsoft terminology | Найдите 20 повторяющихся терминов в своём проекте, выберите форму и контекст использования | Мини-глоссарий и список правил для линтера |
| На ревью приходит 50 однотипных замечаний | IBM quality model + GitHub content principles | Разделите комментарии на формальные и смысловые; первые отдайте линтеру, вторые превратите в review checklist | Карта «машина / человек» для редакционного процесса |
| Локализация постоянно ломает двусмысленные фразы | Google global-audience guidance + IBM globalization principles | Перепишите две страницы без идиом, скрытых местоимений и культурных ссылок | Набор локальных примеров «до / после» |
| ИИ выдаёт убедительный, но сомнительный текст | Наш материал о fact-checking + реальная спецификация продукта | Возьмите один AI draft и пометьте каждое проверяемое утверждение источником истины: код, UI, API schema, SME, тест | Fact-check map вместо субъективного «вроде нормально» |
Практика меняет сам смысл чтения. За вечер вы не «изучили Google Style Guide», зато получили одно доказуемое улучшение и правило, которое можно проверить на следующей странице.
Как превратить чтение в навык
Хороший цикл обучения начинается не со списка литературы, а с дефекта в собственной документации.
Например, ревьюер третий раз пишет «непонятно, что получится после шага». Откройте guidance по procedures у Microsoft и Google, посмотрите несколько реальных страниц GitHub Docs, затем перепишите одну процедуру так, чтобы у ключевых шагов появился наблюдаемый результат. Следующее ревью покажет, исчезла ли проблема. Если решение повторяется, перенесите его в локальный style guide; если правило формализуемо, подумайте о линтере.
Учебный журнал тоже должен хранить не названия прочитанных книг, а изменения: исходный фрагмент, применённое правило, результат ревью и решение, которое команда оставила у себя.
Что читать из книг и что в них уже устарело
Старую книгу не нужно выбрасывать только из-за даты. Полезно отделять модель мышления от интерфейсов и процессов, которые успели измениться.
| Книга | Зачем читать сейчас | Что воспринимать как исторический слой |
|---|---|---|
Docs for Developers (2021) |
Хороший полный цикл: аудитория, планирование, draft, editing, code samples, публикация, feedback, метрики, maintenance | Книга появилась до нынешней волны LLM; AI-assisted authoring и fact-checking придётся достраивать современными практиками |
Developing Quality Technical Information, 3rd ed. (2014) |
Сильная модель качества и редакционного анализа; особенно полезны task orientation, accuracy, completeness, clarity, organization, retrievability | Delivery stack и часть организационного контекста старше современной docs-as-code/LLM среды |
Every Page Is Page One (2013) |
Полезно думать о странице, на которую читатель попал прямо из поиска: контекст, самостоятельность topic, links, metadata | Представления о поиске и каналах доставки стоит переосмысливать с учётом AI answers и современных doc portals |
The Product is Docs |
Полезна как разговор о документации внутри продуктовой команды: аудитория, взаимодействие с QA, support, product management и engineering | Конкретные командные практики нужно проверять против своей организации и сегодняшней автоматизации |
Книга особенно полезна тогда, когда после главы хочется спорить с автором на материале собственного проекта. Слепое следование рецепту пятнадцатилетней давности даёт меньше, чем осмысленное сравнение старой модели с текущим процессом.
Соберите собственный style guide из проверенных решений
Microsoft, Google или GitHub не должны становиться корпоративной конституцией вашей команды. Даже Google прямо ставит project-specific guidance выше общего developer style guide. Локальное правило нужно там, где продукт, аудитория или технология требуют конкретного решения.
Хороший локальный style guide растёт из повторяющихся вопросов. Если три reviewer подряд обсуждают написание одного термина, зафиксируйте термин. Если API examples постоянно оформляются по-разному, определите шаблон request/response. Если каждое ревью спорит о том, писать ли UI label как code или обычный текст, выберите один вариант и запишите его. Правило должно сокращать следующий спор, а не демонстрировать толщину документа.
Для каждого локального правила полезно хранить четыре вещи: проблему, решение, хороший пример и исключение. Большая теория обычно не нужна.
| Поле локального правила | Пример |
|---|---|
| Проблема | В документации встречаются log in, login и sign in для одного действия |
| Решение | В пользовательской инструкции используем sign in; login оставляем только там, где это имя технического объекта |
| Хороший пример | «Sign in to the admin console.» |
| Исключение | Поле API называется login; имя поля не переписываем |
Через несколько месяцев такой файл становится ценнее чужого style guide, потому что содержит решения именно вашей системы. Внешние руководства остаются инструментом для проверки и расширения локальных решений.
Итак, с чего начать на этой неделе
Не пытайтесь прочитать пять больших гайдов подряд. Возьмите одну страницу своего проекта, которая уже получила замечание от пользователя, SME или редактора. Сформулируйте проблему одним предложением и найдите два источника, которые предлагают способ её решить.
На следующий день сделайте версию before/after и покажите её одному человеку, который реально пользуется этой документацией. Ещё через день запишите решение в локальные правила, если оно выдержало проверку. За неделю получится не список «что я прочитал», а один улучшенный материал, одна проверенная редакционная гипотеза и, возможно, одно новое правило команды.
Через месяц повторите цикл на другой проблеме. Темп выглядит скромнее марафона из двадцати книг, зато формирует собственную инженерную практику работы с документацией.
