Привет! Я Марина Виноградова, технический писатель VK. Прочитав название этой статьи, вы подумаете: «Документация же не пахнет!» Это правда, если речь не о её бумажных копиях… Но почему тогда пахнет код? Запахи кода — это фигура речи, обозначающая признаки проблем в коде и необходимости рефакторинга. Запахи кода обращают внимание на недочёты в проектировании и говорят нам о низком качестве кода. Мы можем написать как код, так и документацию. Чистыми с первого раза они никогда не будут, нужно пропускать их через рецензирование или рефакторинг.

Рассмотрим, как основные запахи кода с ресурса Refactoring Guru (сейчас он запрещен на территории РФ) ложатся на документацию. Это лишь малая часть того, на что стоит обращать внимание при её разработке.

Раздувальщики

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

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

Пример: одностраничная документация без меню и якорей.

Что понимается под хорошей структурой документации? Рекомендуется следить за тем, чтобы уровень вложенности на странице не превышал заголовков 4-го уровня. Но что делать, когда в документации много тем, по которым делится документация? Например в Unity Manual самая большая вложенность, какая мне встречалась: 7 разделов в меню, считая саму страницу, и 1 подраздел на странице, итого 8! Это много. Продукт масштабный и сложный, в таких случаях почти ничего нельзя сделать с точки зрения документации. Но есть одна дизайнерская хитрость:  вы можете добавить в меню верхнюю по иерархии тему статично, а уже под ней перечислить нижние темы. Так сделано в документации Xsolla Login API.

Нарушители объектного дизайна

«Все эти запахи являют собой неполное или неправильное использование возможностей объектно-ориентированного программирования.»

Чтобы разобраться в этом запахе, копнём глубже. Он понимает под собой темы:

• Альтернативные классы с разными интерфейсами.

• Отказ от наследования.

• Операторы switch.

• Временное поле.

Альтернативные классы с разными интерфейсами

«Два класса выполняют одинаковые функции, но имеют разные названия методов.»

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

• в компании несколько разных продуктов, но точка входа одинакова для всех;

• описываются разные настройки, возможности одного и того же блока или раздела. 

Также эта ситуация напоминает неконсистентность в использовании терминов: мы называем одно и то же разными именами.

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

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

Отказ от наследования

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

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

Здесь также говорится о дублирующих частях документации. Более подробно этот аспект описаны в разделе Альтернативные классы с разными интерфейсами: дублирующие части нужно по мере необходимости выносить в отдельные файлы и встраивать их в другие страницы.

Операторы switch

«У вас есть сложный оператор switch или последовательность if-ов.»

Как и сложный оператор switch, трудно воспринимать длинные вложенные списки и таблицы. Лучше делить их на небольшие группы. Иногда это сделатьсложно, но всё же возможно. Из полотна текста вы получите несколько подразделов.

Временное поле

«Временные поля — это поля, которые нужны объекту только при определённых обстоятельствах. Только тогда они заполняются какими-то значениями, оставаясь пустыми в остальное время.»

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

Чаще всего подобные страницы не выкладывают для всех, а делают доступными либо по определённым правам, либо по прямой ссылке.

Также можно подумать, что в компании сменилась версия продукта. Тогда документация на более старые версии считается, также как и устаревшие методы в разработке, deprecated, и в скором времени перестает поддерживаться, а иногда вообще закрывается.

Утяжелители изменений

«Эти запахи приводят к тому, что при необходимости что-то поменять в одном месте программы, вам приходится вносить множество изменений в других местах. Это серьезно осложняет и удорожает развитие программы.»

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

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

К документации в крупных компаниях относятся как к продукту, который живёт и изменяется по своим правилам. Взгляд технического писателя на документацию со временем меняется, как и правила, которым технические писатели следуют. Это идёт на пользу документации, потому что делает её понятнее и предсказуемее для пользователя.

Замусориватели

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

Здесь будет немножко инфостиля, уж простите. В технической документации (я не говорю про ту, что написана по ГОСТ) не место стоп-словам. Главред под ними понимает:

• вводные;

• оценки;

• усилители;

• обобщающие и неопределённые;

• штампы и канцеляризмы.

Я бы ещё добавила в этот список жаргонизмы и сленг. Всё это делает текст двусмысленным, грязным и неконкретным. Обращайте внимание на те слова, которые вы используете при написании документации. Заводите правила на стоп-слова в вашей компании.

Опутыватели связями

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

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

При этом нужно понимать, что документация настроек может содержать:

• дублирующие части, когда какие-то настройки нескольких продуктов совпадают;

• перекрёстные ссылки на документацию отличающейся настройки других продуктов.

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