Самый эффективный способ — не создавать её вообще. Как известно, самая плохая документация лучше, чем никакой.
Но кто-то может возразить, что если у вашего продукта нет никакой доки, то нельзя сказать, что вы создали худшую. И формально будет прав. Так что давайте разберемся, как сделать худшую.
Статья будет полезна всем, кто может испортить документацию: техническим писателям, аналитикам, владельцам продуктов, менеджерам, тимлидам.
Выберите неудобный инструмент
Если вы пришли на проект на ранней стадии, где ещё не сложилось никаких практик вокруг документации, вам будет достаточно легко свести её пользу к нулю. Как в любом деле, начните с выбора правильного инструмента.
Проанализируйте, какие задачи должна решать ваша документация, какие к ней требования, и каким будет процесс её создания и поддержки. Выберите тот инструмент, который максимально для этого неудобен. Причем как для читателей доки, так и для контрибьюторов — тех, кто будет писать и поддерживать её вместе с вами.
Помните, что хорошие контрибьюторы в команде могут помешать вашей цели, сделав документацию не такой уж плохой. Ваша задача — максимально их демотивировать на раннем этапе, чтобы они боялись даже притронуться к ней.
Например, если команде нужна внутренняя база знаний, где можно было бы свободно писать заметки и оставлять друг другу комментарии без лишних приседаний — поднимите для них сайт с Docs as Code. Это будет воспринято командой с особенным «энтузиазмом», если большинство сотрудников в команде это аналитики или дизайнеры, которые в глаза не видели Git.
Обратный пример: если продукту нужна внешняя пользовательская документация, источник истины, начните вести её в Confluence или другой подобной вики-системе. Желательно чтобы оформление было невзрачным, интерфейс перегруженным, а кто угодно из команды мог вносить любые правки без всякого контроля.
При любых условиях, достаточно неудобными для всех будут вордовские файлы на облачном диске. Если продукту нужна документация по ГОСТу, то это отличный благовидный предлог выбрать именно этот вариант. Если кто-то из коллег предложит вести два набора документации — для людей и для официальных структур, парируйте тем, что документация должна быть единым источником правды о продукте и любое дублирование неприемлемо. Игнорируйте инструменты типа Pandoc, которые позволяют импортировать документацию с веб- в печатные форматы.
Помните, что выбор неподходящего инструмента — это важный первый шаг, который задаст тон всему остальному бардаку.
Пустите процессы на самотёк
Лучше вообще забудьте словосочетание «процесс документирования». Отпустите вашу документацию в свободное плавание. В этом помогут несколько простых принципов:
Актуализация доки не является этапом в задачах на разработку фичей в Jira и вообще полностью исключена из цикла разработки продукта. Документация дополняется спонтанно, когда кто-то обнаруживает, что в ней написана неправда.
Писать новые разделы и вносить правки могут любые участники команды, а в идеале даже пользователи. При этом правки не проходят никакого ревью ни с технической, ни с текстовой точки зрения. Сразу в прод!
Нет никаких рекомендаций, которые бы подсказывали контрибьюторам, как написать хороший текст и как приносить правки. Каждый пишет, как хочет.
Фидбэк от пользователей игнорируется.
Тексты проходят общее ревью каждый год, 30 февраля.
Если вас просят всё же сделать какую-то редполитику с рекомендациями, сведите её к мелочам, вроде «пишем ли букву ё» и «какие кавычки используем». Будет отлично, если вам удастся регулярно буллить коллег за то, что они не следуют этим правилам. Помните про демотивацию.
Здесь я мог бы закончить статью, ведь неэффективные процессы в сочетании с неудобным инструментом сделают остальную работу за вас. Но эти методы возможны только если вы стоите у истоков продукта. А что если вы пришли на проект, где уже есть какие-то адекватные процессы и выбран инструмент? Не отчаивайтесь! Пока у вас есть возможность непосредственно влиять на документацию, вы всё ещё можете сделать её практически бесполезной.
Сломайте структуру
Даже если ваша команда умников завела документацию на современном сайте с прикрученным ИИ-поиском, пользователь будет долго собирать нужную информацию по крупицам, если вы раскидаете её достаточно непредсказуемо. Несколько общих соображений на этот счёт:
Выясните, кто ваш средний пользователь: что он знает на входе и что надеется узнать, прочитав документацию (ха, наивный). Начинайте каждый раздел так, будто пользователь уже всё знает. Никаких вводных пояснений, никаких туториалов или примеров. Вашему продукту не нужны слабые юзеры, неспособные разобраться в нём самостоятельно.
Проанализируйте вероятные запросы к документации — зачем вообще человек захочет её открыть. Организуйте структуру так, чтобы в разделах было либо недостаточно информации для покрытия запроса, либо было много лишнего. Например, пользователь захочет узнать, как создать бэкап и пойдёт в раздел «Бэкапы». Предложите ему сперва прочитать обо всех тонкостях вашей архитектуры бэкапирования, с исторической справкой и почему не выбрано другое решение. Навигацию по подзаголовкам отключите.
Никогда не добавляйте перекрестные ссылки на другие разделы, которые хоть как-то связаны по смыслу с текущим. И наоборот, добавляйте как можно чаще ссылки на разделы, которые слаборелеванты и никак не помогут пользователю решить текущий запрос.
Заголовки подбирайте так, чтобы они как можно меньше сообщали о содержании разделов. Пользователь никогда не должен знать наверняка, что он узнает на той или иной странице. Люди любят интригу.
Сделайте подзаголовки такими короткими, чтобы их смысл, если и был понятен, то только в контексте всего раздела. Например, если это раздел «Бэкапы» и в нем есть подраздел «Как создать бэкап», сократите название подраздела до «Создать». Для человека разница может быть не особо значительна, но помните, что теперь вы пишете доку не только для людей. ИИ-поисковики часто используют подзаголовки при чанкировании и при определении релевантности чанка запросу. Чем более неявные подзаголовки вы используете, тем сложнее будет железяке отнять у вашей документации звание худшей.
Пишите замысловато и непоследовательно
Вы практически у цели. Осталось только написать уродливый текст.
На этом этапе можете подключить ИИ-шку, чтобы меньше печатать. Обычно она неплохо справляется с написанием водянистых текстов, которые почти не сообщают полезной информации, хотя по форме выглядят хорошо. Последнее для вас нежелательно, поэтому чтобы добиться лучших результатов, проверяйте и редактируйте нейрослоп, следуя рекомендациям:
Старайтесь не использовать абзацы. И по возможности объединяйте несколько предложений в одно.
Вместо списка используйте перечисление через запятую, так читателю будет намного сложнее уследить за смыслом. Но если список сделать всё же пришлось, проверьте, чтобы его пункты были грамматически неконсистенты и не связаны с вводным предложением.
Используйте настолько тяжелые канцелярские конструкции, насколько возможно. В этом вам помогут такие замечательные слова как «необходимо», «обязательно», «выполнить» и «осуществить». Они обладают суперсилой превращать глаголы в существительные и размывать смысл сказанного:
❌Нажмите кнопку
✅Необходимо выполнить нажатие на кнопку❌После копирования система проверяет контрольные суммы
✅После завершения копирования обязательно осуществляется проверка контрольных суммОбратите внимание, как во втором примере чудесно пропало действующее лицо — теперь пользователь должен угадать, должен ли он что-то сделать или проверка происходит сама. Пользователи будут благодарны за то, что вы тренируете их сообразительность и интуицию.
В предложении сначала сообщайте читателю новую информацию, а затем то, что он уже знал. В частности, придерживайтесь последовательностей «что нужно сделать — зачем» и «что нужно нажать — где». Так пользователю придется читать все предложения целиком и чаще перечитывать их. И не забывайте наваливать канцелярщины:
❌Чтобы сохранить проект, в правой верхней части окна нажмите Сохранить.
✅Необходимо выполнить нажатие на кнопку Сохранить в правой верхней части окна, для сохранения проекта.Если какая-то часть информации актуальна только при определённых условиях, сообщите эти условия в самом конце. Это касается и предварительных действий:
❌Перед записью в базу данных проверьте, что на диске достаточно места.
Чтобы добавить строку в базу данных, используйте команду INSERT: …
✅Чтобы добавить строку в базу данных, используйте команду INSERT: …
Перед записью в базу данных проверьте, что на диске достаточно места.Может показаться что это мелочь, но именно такая последовательность повышает шанс, что пользователь не увидит предупреждение до того, как начнет следовать инструкции. База переполнится и уйдёт в read-only. Это будет отличный урок для пользователя, что сперва нужно полностью внимательно читать документацию.
Заключение
Используя перечисленные здесь принципы, вы неизбежно сделаете документацию вашего продукта совершенной. Совершенно бесполезной.
Но если вы чувствуете, что материала этой статьи вам недостаточно и нужны подробности, изучите другие мои статьи и полезные рекомендации из других источников и следуйте им наоборот:
Статья о том, как можно выстроить рабочий процесс создания и поддержки документации для разных платформенных продуктов. Убедитесь, что ваши процессы не похожи на это.
Распространенный подход к структурированию разделов документации — Diátaxis. Держитесь от него подальше. Есть изложение в статье на русском языке с примерами.
Если вам приходится писать на английском, то чтобы делать это хуже, используйте плохие примеры из серии статей Как улучшить английский в документации. Там есть часть 2 и часть 3.
Осуществить написание непонятных текстов вам поможет избегание принципов инфостиля, которые изложены в книге «Пиши, сокращай» Максима Ильяхова и Людмилы Сарычевой.
Успехов и позитивного начала апреля!
Нет, приглашения в телеграм-канал в конце не будет, но вы можете подписаться на меня на Хабре или добавиться в Линкед.
