Как стать автором
Обновить

Ошибки технарей, которые пишут документацию для разработчиков

Время на прочтение7 мин
Количество просмотров5.8K

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

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

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

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

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

«Писать документацию — не входит в мои основные задачи»

Однажды в ответ на правки аналитик мне ответил, что в его задачи не входит грамотно писать и знать об инфостиле, потому что он аналитик, и у него совсем другие приоритеты. Ну что тут можно сказать? 

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

Hotfix:

  • Используйте среду разработки (IDE) вместо Confluence, GoogleDocs, Word. Среда разработки позволяет подключать плагины и писать собственные скрипты для разработки документации. VSCode — идеальный инструмент для меня, у вас могут быть свои фавориты среди приложений.

  • Ставьте плагины проверки орфографии и семантики для ваших IDE.

  • Разрабатывайте собственные правила с оглядкой на глобальное сообщество технических писателей.

  • Шаблонизируйте все, что только можно. Шаблоны уменьшают вероятность ошибиться.

Readme:

Spellcheking sketch
Автор скетча — Linette Voller (https://twitter.com/mslanei)
Автор скетча — Linette Voller (https://twitter.com/mslanei)

«Кому надо, тот поймет»

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

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

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

Пишите, как вам хочется, на Хабре. Рассказывайте любым языком про новую фичу на митапе или в подкасте. Для документации подбирайте самые простые слова и конструкции. 

Главный парадокс технического писательства — 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:

Писанина в одиночку

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

Hotfix:

  • Начинайте всегда с тезисного плана и показывайте его вашему заказчику — PO, CTO, тимлиду.

  • Пишите поэтапно.

  • Согласовывайте частями.

  • Собирайте встречи с командой.

  • Собирайте обратную связь.

Страх обратной связи

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

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

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

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

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

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

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

Hotfix:

  • Введите практику перекрестной вычитки в своей команде.

  • Пройдите курсы по критическому мышлению.

  • Освойте базовые техники медитации.

  • Прокачайте свой эмоциональный интеллект.

Readme:

Теги:
Хабы:
Всего голосов 14: ↑11 и ↓3+13
Комментарии9

Публикации

Истории

Работа

Ближайшие события

Антиконференция X5 Future Night
Дата30 мая
Время11:00 – 23:00
Место
Онлайн
OTUS CONF: GameDev
Дата30 мая
Время19:00 – 20:30
Место
Онлайн
Конференция «IT IS CONF 2024»
Дата20 июня
Время09:00 – 19:00
Место
Екатеринбург
Summer Merge
Дата28 – 30 июня
Время11:00
Место
Ульяновская область