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

Как команда платформы, которая помогает техническим писателям управлять документацией без головной боли, мы каждый день видим, как сложные проекты превращаются в понятные руководства, API-доки — в четкие инструкции для разработчиков, а запутанные процессы — в прозрачные чек-листы. И знаем, что техническое письмо — это не только шаблоны, ГОСТы, версионный контроль и так далее. Это еще и ясность формулировок, логика повествования, эмпатия к тем, кто будет читать ваш текст.

Даже самые крутые инструменты (вроде Документерры) не могут вложить эти навыки в писателя. Но мы можем предложить список для чтения ;) 

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

Читайте подборку, сохраняйте в закладки, делитесь, чем еще дополнить список — и давайте делать мир документации лучше вместе!

Основы технического письма

• Ю.В. Кагарлицкий, «Разработка документации пользователя программного продукта. Методика и стиль изложения»

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

• Руководство по стилю от Google 

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

• В. А. Глаголев, «Разработка технической документации. Руководство для технических писателей и локализаторов ПО»

  Несмотря на солидный «возраст» книги, это все еще достаточно удобный источник базовой информации о разработке текстовой технической документации на аппаратно-программные комплексы, автоматизированные системы и программные продукты. ГСИ, ЕСКД, ЕСПД, ЕСТД, КСАС и так далее — четким и доступным языком.

• Кристофер Гейлс, команда Splunk, “The Product is Docs: Writing Technical Documentation in a Product Development Group”

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

Стиль, ясность и структура

• Джаред Бхатти, Сара Корлейссен, Джен Лэмборн, Дэвид Нуньес, Хайди Уотерхаус, “Docs for Developers: An Engineer’s Field Guide to Technical Writing”

  Must-read о том, как писать, встраивать и поддерживать документацию, а главное — как делать это в команде.

• Барбара Минто, «Принцип пирамиды Минто»

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

• Уильям Зинсер, «Как писать хорошо»

  Учит избавляться от «мусора» в тексте (лишние слова, сложные конструкции).

• Энн Джентель, “Docs Like Code”
  О том, как применять подходы разработчиков (например, Git, Markdown) для создания документации. Идеально для Agile-команд.

• Робин Уильямс, “The Non-Designer’s Design Book”

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

Дополнительные ресурсы

• Уильям Странк мл., «Элементы стиля»

  Классика, объясняющая, как писать ясно и лаконично. Акцент на упрощении текста, избегании сложных конструкций и точности формулировок. 

• Чикагское руководство по стилю

  Авторитетный справочник по грамматике, пунктуации и форматированию. Незаменим для редакторов и авторов технических текстов на английском.

• А. Мильчин, Л. Чельцова, «Справочник издателя и автора»
  Настольная книга для работы с текстами: от правописания до литературной правки. Особенно полезна для русскоязычных писателей.

• М. Ильяхов, Л. Сарычева, «Пиши, сокращай»

  Книга о том, как избавляться от «воды» в текстах, делать их конкретными и понятными. 

• Нора Галь, «Слово живое и мертвое»

  Классика антиканцелярита. Полезна всем пишущим независимо от целей их текстов.

• Ли ЛеФевер, «Искусство объяснять»

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

* * *

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

Но теория без практики, как известно, мертва. Возьмите одну методику из нашего списка (например, принцип пирамиды Минто) и попробуйте внедрить ее в свой проект бесплатно на триале нашей платформы — все необходимое для экспериментов уже под рукой.

Что из этого списка вы уже читали? Какие книги добавили бы? Делитесь своими находками в комментариях — давайте вместе соберем идеальную библиотеку технического писателя!