Техническая документация — это не просто набор инструкций, а мощный инструмент, который делает продукт понятным, удобным и, в конечном счете, успешным. Но чтобы создавать такие материалы, одного знания инструментов мало — нужно понимать, как ясно излагать мысли, структурировать информацию и говорить с аудиторией на одном языке. Поговорим о книгах, которые помогут научиться писать такую документацию.
Как команда платформы, которая помогает техническим писателям управлять документацией без головной боли, мы каждый день видим, как сложные проекты превращаются в понятные руководства, 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”
Как создавать визуально привлекательные, понятные и удобные для чтения документы с помощью контраста, выравнивания и других принципов.
Дополнительные ресурсы
Уильям Странк мл., «Элементы стиля»
Классика, объясняющая, как писать ясно и лаконично. Акцент на упрощении текста, избегании сложных конструкций и точности формулировок.
Чикагское руководство по стилю
Авторитетный справочник по грамматике, пунктуации и форматированию. Незаменим для редакторов и авторов технических текстов на английском.
А. Мильчин, Л. Чельцова, «Справочник издателя и автора»
Настольная книга для работы с текстами: от правописания до литературной правки. Особенно полезна для русскоязычных писателей.М. Ильяхов, Л. Сарычева, «Пиши, сокращай»
Книга о том, как избавляться от «воды» в текстах, делать их конкретными и понятными.
Нора Галь, «Слово живое и мертвое»
Классика антиканцелярита. Полезна всем пишущим независимо от целей их текстов.
Ли ЛеФевер, «Искусство объяснять»
Счастье — это когда тебя понимают. Счастье вдвойне — когда понимают твою документацию. В этой книге расскажут о том, как передать сложную информацию через историю и визуальные элементы.
* * *
Техническое письмо — это не про бесконечные нудные мануалы. Это про магию превращения сложного в простое. И книги из нашей подборки — не просто «галочка» в списке прочитанного. Это ваши будущие союзники в борьбе с неоднозначными ТЗ, капризными разработчиками и вечным «нам нужно вчера».
Но теория без практики, как известно, мертва. Возьмите одну методику из нашего списка (например, принцип пирамиды Минто) и попробуйте внедрить ее в свой проект бесплатно на триале нашей платформы — все необходимое для экспериментов уже под рукой.
Что из этого списка вы уже читали? Какие книги добавили бы? Делитесь своими находками в комментариях — давайте вместе соберем идеальную библиотеку технического писателя!
