Краткий разбор типичных ошибок и когнитивных искажений при написании технической документации для разработчиков. Обнаружение и hotfix этих дефектов призван сделать ваши тексты лучше, а процесс работы с ними — чуть более осознанным.
Я разрабатываю техническую документацию с нуля и много работаю с уже написанной докой для огромной технологической платформы. Редактирую, даю комментарии по стилю и стандарту, слежу за визуальной и семантической чистотой, разрабатываю и поддерживаю стайлгайд, общаюсь с командой разработки, управляю процессами согласования в сложных корпоративных цепочках.
Документацию, которая поступает ко мне на вход, пишут технические писатели, аналитики, разработчики и даже тимлиды. Некоторые команды начали писать ее в древние времена — несколько лет назад.
За полтора года работы с докой, написанной людьми с разными уровнем подготовки и опытом, у меня сформировался словарь типичных выражений и чек-лист поведенческих паттернов, которые откровенно портят качество документации и мешают рабочему процессу.
Если вы поймали себя на том, что какие-то фразы служат вашими аргументами в профессиональном общении, и в процессе работы с текстом вы действуете похожим образом, поздравляю. Вы на полпути к тому, чтобы заменить неработающие паттерны на эффективные.
«Писать документацию — не входит в мои основные задачи»
Однажды в ответ на правки аналитик мне ответил, что в его задачи не входит грамотно писать и знать об инфостиле, потому что он аналитик, и у него совсем другие приоритеты. Ну что тут можно сказать?
Неграмотный аналитик — горе в семье, а заниматься документацией по остаточному принципу — это стрелять себе в ногу всей командой разработки. Либо занимайтесь этим хорошо, либо отдайте задачу другому, более заинтересованному в конечном результате человеку. Если ваше руководство не разделяет такой подход, сделайте разработку документации по крайней мере удобной и технологичной.
Hotfix:
Используйте среду разработки (IDE) вместо Confluence, GoogleDocs, Word. Среда разработки позволяет подключать плагины и писать собственные скрипты для разработки документации. VSCode — идеальный инструмент для меня, у вас могут быть свои фавориты среди приложений.
Ставьте плагины проверки орфографии и семантики для ваших IDE.
Разрабатывайте собственные правила с оглядкой на глобальное сообщество технических писателей.
Шаблонизируйте все, что только можно. Шаблоны уменьшают вероятность ошибиться.
Readme:
Все материалы с конференции Write the docs (Прага, 2022).
Доклад Beyond spell checking - what else can we check automatically техничекого писателя компании Aiven.
Spellcheking sketch
Список литературы и основные правила технического письма. Автор: технический писатель компании Tink Никлас Пивик.
«Кому надо, тот поймет»
Неуместная подача информации — пожалуй, главный камень преткновения для тех, кто никогда не работал с текстами для аудитории.
«Я пишу для тех, кто в этом разбирается», «кому надо, тот поймет», «у нас все так говорят» — эти фразы будто вживляют в головы на одном тайном заводе всем специалистам, которые не хотят работать с чистотой и ясностью текста технической документации.
Профессиональный жаргон и англицизмы требуют аккуратности и консистентности. Это специи, которые могут придать пикантный вкус, и при их неуместности и избыточности превратить блюдо в отраву, то есть, документацию — в записки сумасшедшего инженера.
Пишите, как вам хочется, на Хабре. Рассказывайте любым языком про новую фичу на митапе или в подкасте. Для документации подбирайте самые простые слова и конструкции.
Главный парадокс технического писательства — writing for skimming (вольный перевод цитаты из книги Docs for developers — писательство для беглого пролистывания).
Это печально, но факт — документацию писать трудно, она почти всегда объемна, но читают ее не от корки до корки, а проскролливая или через поиск. Поэтому текст должен быть понятным с любого места. Часто документация для разработчиков ПО — это лицо продукта, поэтому забота о том, как пишутся руководства, должна быть в приоритете.
Hotfix:
Англицизмы и профессиональный жаргон. Правило простое — сверяйтесь по словарям и действующим нормам. Слово есть в орфографическом словаре? Пишите по нормам русской орфографии.
Слова нет в русском орфографическом словаре. Пишите в оригинале, в скобках давайте перевод, заносите слово в термины. Проблема слов, которых нет в словаре — общая для всего мира независимо от языка и имеет даже свою аббревиатуру OOV (Out of vocabulary words).
И это не повод в документации писать так, как общаются между собой инженеры в баре. И уж точно не повод придумывать длинное выражение на русском для короткого слова на английском.
Консистентность. Выбранного написания придерживайтесь все и везде. Для этого удобно иметь глоссарий с терминами, к которому будет обращаться разработчик конкретной главы документации.
Readme:
Книга, написанная для разработчиков — Docs for developers. Обязательна к прочтению всеми, кто работает с технической документацией, разрабатывает, пишет и поддерживает ее. Авторов у книги несколько, все звездные и именитые в мире технического писательства.
Всегда держите под рукой:
«Так это же техническая документация, тут особый язык»
Так мне говорят те, кто любит обороты типа «осуществляет установку», «следует воспользоваться», «обеспечьте выполнение».
Канцелярит — это уничтожитель ясности, здравого смысла и самая настоящая поэзия вогонов, которая, как известно, является самой ужасной вещью во вселенной.
«Технические же писатели, по словам техписа Никласа Пивика, — «подобны помощникам наемных убийц: они предоставляют материал, чтобы конкретный человек мог как можно быстрее закончить свою миссию и уйти. Читатели ценят краткость. Быть кратким (в техническом письме) означает по-настоящему заботиться о читателе».
Оригинал и ссылка на весь текст
Канцелярит — это вчерашний век. От него избавляются даже юристы и чиновники. Пришла пора и вам распрощаться с языком пыльных казенных контор прошлого столетия.
Hotfix:
Избавьтесь от словесного мусора. Выбросьте все свои «непосредственно», «на самом деле», «собственно». Just stop it.
Прочтите все книги Ильяхова.
Readme:
Книга Пиши, сокращай.
Книга Ясно, Понятно.
Техника Одно предложение на одной строке.
«Это написано в коде, мы менять не будем»
Лезть в код? Ну нет. Некоторые писатели тянут одну ошибку на протяжении всей документации только потому, что разработчик так написал это слово в комментариях к коду, или из-за забытого мокапа в интерфейсе.
Код и интерфейс не высечены из камня. Неграмотные комментарии в коде, странные названия переменных, корявые сообщения об ошибках и дикие фразы в интерфейсах должны быть исправлены.
Hotfix:
Лезьте в код.
Лезьте в интерфейс.
Назначайте встречи с разработчиками и дизайнерами.
Предлагайте варианты взаимодействия. Будете вы менять тексты в своей ветке, онлайн пройдетесь вместе по текстам и скажете, что поправить, пришлете правки в мессенджер — вариантов получить нужный результат достаточно, один из них обязательно сработает.
Readme:
Читайте все про умение договариваться и взаимодействовать в команде, например, журнал Кинжал.
«Какая разница, какого цвета диаграммы и какие скриншоты, главное — суть»
Пестрые, не сочетающиеся между собой диаграммы и отрисованные процессы в нотациях UML, BPMN, неаккуратные и неуместные скриншоты — реальность, с которой приходится работать.
Трепетно относитесь к цветовой гамме и бережно — к глазам ваших читателей. Находитесь в мире читателя, делайте ему удобно и приятно, будто это ваш друг, с которым вы хотите поделиться занятным устройством технического модуля или диаграммой развертывания.
Hotfix:
Найдите брендбук и используйте корпоративные цвета оттуда.
Не используйте цвета вообще.
Делайте все диаграммы в едином стиле.
Если получаете от архитектора неприличного вида диаграмму, переделайте ее сами, пусть в следующем релизе. Согласуйте ее с архитектором.
Стремитесь к машиночитаемому формату, чтобы проще было переделывать и обновлять визуальную информацию в следующих релизах.
Используйте скриншоты только там, где без них точно нельзя обойтись. Поддерживать скриншоты — всегда дорого.
Readme:
Школа Дмитрия Барбанеля, например, Киоск.
Велосипед с квадратными колесами: мы не смотрим на других, или бездумный повтор за конкурентами
Бездумный копипаст — выстрел себе в ногу. Игнорировать best practices нельзя, но тупо делать такой же велосипед, даже не поразмыслив, зачем и кому от этого станет лучше — бездарная трата времени и бюджетов.
Другая крайность и большая ошибка — вообще не смотреть на документацию, написанную другими, не изучать аналоги, не исследовать целевую аудиторию и не смотреть на то, что востребовано теми, кто пишет и теми, кто читает.
Эти два крайних полюса — колеса велосипеда, на котором дальше ближайшей лужи не уедешь.
Hotfix:
Смотрите, читайте, анализируйте, исследуйте, тестируйте гипотезы. Расширяйте кругозор и тренируйте насмотренность.
Если вы решили придумывать что-то свое в сфере разработки документации, позаботьтесь о том, чтобы внести вклад в глобальное сообщество технических писателей, и заранее определитесь, каким он будет.
Readme:
И еще раз — книга Docs for developers.
Канал Technical writerHQ.
Писанина в одиночку
Написать все главы документации самостоятельно и отдать на согласование — это самый верный способ разработать бесполезную документацию и написать совсем не то, что имел в виду инженер.
Hotfix:
Начинайте всегда с тезисного плана и показывайте его вашему заказчику — PO, CTO, тимлиду.
Пишите поэтапно.
Согласовывайте частями.
Собирайте встречи с командой.
Собирайте обратную связь.
Страх обратной связи
Технические писатели — это, как правило, не копирайтеры и не редакторы, поэтому большинство из них мало работает с обратной связью.
Они реже набивают шишки от заказчиков ПО, меньше заинтересованы в том, чтобы клиент был доволен, чем игроки на стороне продукта.
С одной стороны, это большой плюс для нервной системы технического писателя, с другой — полная беззащитность перед правками, буквально розовое пузико ежа, который при любой обратной связи превращается в трясущийся клубок из иголок.
Болезненная реакция на критику может мимикрировать под дисциплину и прикрыться дедлайнами. Люди тратят часы на обсуждения того, почему им не нужно переделать и улучшить текст.
Буквально целые рабочие дни команды готовы сжечь, чтобы отстоять свое право не работать с текстом и оставить все как есть. Потому что на документацию нет времени, и она уже была один раз написана, критических замечаний там нет — такой аргумент тоже встречается в рабочей рутине.
Признаюсь, у меня другая сторона профдеформации — за долгие годы работы с текстами в агрессивной среде заказчиков и пользовательских комментариев я постоянно прокручиваю в голове десятки вариантов восприятий одного и того же предложения, прежде чем отпустить текст на волю.
Нести в себе груз внутренних диалогов с сильными оппонентами и жирными троллями — не самый легкий способ профессионально расти, однако в конечном счете это мне помогает в работе, дает право делиться опытом и быть экспертом.
Hotfix:
Введите практику перекрестной вычитки в своей команде.
Пройдите курсы по критическому мышлению.
Освойте базовые техники медитации.
Прокачайте свой эмоциональный интеллект.
Readme:
Книга Личность и групповая динамика. Как каждый из нас влияет на окружающих. Автор Лайонел Стэйпи.
Книга Эмоциональная гибкость. Автор Кэрри Флеминг.
