Запахи технической документации
Привет! Я Марина Виноградова, технический писатель VK. Прочитав название этой статьи, вы подумаете: «Документация же не пахнет!» Это правда, если речь не о её бумажных копиях… Но почему тогда пахнет код? Запахи кода — это фигура речи, обозначающая признаки проблем в коде и необходимости рефакторинга. Запахи кода обращают внимание на недочёты в проектировании и говорят нам о низком качестве кода. Мы можем написать как код, так и документацию. Чистыми с первого раза они никогда не будут, нужно пропускать их через рецензирование или рефакторинг.
Рассмотрим, как основные запахи кода с ресурса Refactoring Guru (сейчас он запрещен на территории РФ) ложатся на документацию. Это лишь малая часть того, на что стоит обращать внимание при её разработке.
Раздувальщики
«Раздувальщики представляют код, методы и классы, которые раздулись до таких больших размеров, что с ними стало невозможно эффективно работать. Все эти запахи зачастую не появляются сразу, а нарастают в процессе эволюции программы (особенно когда никто не пытается бороться с ними).»
В категорию раздувальщиков попадает документация, в которой отсутствует хорошая структура. Так происходит, когда страницы в документацию добавляют хаотично: не в определённое и продуманной место, а валят в кучу. И чем больше становится документация, тем сложнее её воспринимать и ориентироваться в ней.
Пример: одностраничная документация без меню и якорей.
Что понимается под хорошей структурой документации? Рекомендуется следить за тем, чтобы уровень вложенности на странице не превышал заголовков 4-го уровня. Но что делать, когда в документации много тем, по которым делится документация? Например в Unity Manual самая большая вложенность, какая мне встречалась: 7 разделов в меню, считая саму страницу, и 1 подраздел на странице, итого 8! Это много. Продукт масштабный и сложный, в таких случаях почти ничего нельзя сделать с точки зрения документации. Но есть одна дизайнерская хитрость: вы можете добавить в меню верхнюю по иерархии тему статично, а уже под ней перечислить нижние темы. Так сделано в документации Xsolla Login API.
Нарушители объектного дизайна
«Все эти запахи являют собой неполное или неправильное использование возможностей объектно-ориентированного программирования.»
Чтобы разобраться в этом запахе, копнём глубже. Он понимает под собой темы:
Альтернативные классы с разными интерфейсами.
Отказ от наследования.
Операторы
switch.Временное поле.
Альтернативные классы с разными интерфейсами
«Два класса выполняют одинаковые функции, но имеют разные названия методов.»
Это очень напоминает дублирующие части документации, которые находятся на разных страницах: чаще всего логические повторы или описания одной и той же настройки. Такое бывает, если:
в компании несколько разных продуктов, но точка входа одинакова для всех;
описываются разные настройки, возможности одного и того же блока или раздела.
Также эта ситуация напоминает неконсистентность в использовании терминов: мы называем одно и то же разными именами.
Дублирующие части нужно по мере необходимости выносить в отдельные файлы и встраивать их в другие страницы. Если вы используете подход к документированию Single-source publishing, это решается из коробки. Все поддерживающие его инструменты умеют повторно использовать контент. А в случае с подходом Docs as Code придётся немного попотеть, так как не все подобные инструменты поддерживают такую возможность, часто приходится реализовывать её с нуля.
Не забывайте также поддерживать консистентность не только в пределах одной страницы, но в пределах всех документации компании.
Отказ от наследования
«Если подкласс использует лишь малую часть унаследованных методов и свойств суперкласса, это является признаком неправильной иерархии. При этом ненужные методы могут просто не использоваться либо быть переопределёнными и выбрасывать исключения.»
Я это понимаю так: если есть большой класс с разными методами, а другим классам нужны лишь конкретные, повторяющиеся методы, стоит выделить их из большого класса в отдельный.
Здесь также говорится о дублирующих частях документации. Более подробно этот аспект описаны в разделе Альтернативные классы с разными интерфейсами: дублирующие части нужно по мере необходимости выносить в отдельные файлы и встраивать их в другие страницы.
Операторы switch
«У вас есть сложный оператор switch или последовательность if-ов.»
Как и сложный оператор switch, трудно воспринимать длинные вложенные списки и таблицы. Лучше делить их на небольшие группы. Иногда это сделатьсложно, но всё же возможно. Из полотна текста вы получите несколько подразделов.
Временное поле
«Временные поля — это поля, которые нужны объекту только при определённых обстоятельствах. Только тогда они заполняются какими-то значениями, оставаясь пустыми в остальное время.»
Применительно к документации этот запах говорит о том, что есть страницы, которые нужны только ограниченному кругу пользователей. Обычно таких пользователей в несколько раз меньше основной аудитории. Так происходит, когда некоторая функциональность разрабатывается под конкретного партнёра компании или для решения узконаправленной задачи.
Чаще всего подобные страницы не выкладывают для всех, а делают доступными либо по определённым правам, либо по прямой ссылке.
Также можно подумать, что в компании сменилась версия продукта. Тогда документация на более старые версии считается, также как и устаревшие методы в разработке, deprecated, и в скором времени перестает поддерживаться, а иногда вообще закрывается.
Утяжелители изменений
«Эти запахи приводят к тому, что при необходимости что-то поменять в одном месте программы, вам приходится вносить множество изменений в других местах. Это серьезно осложняет и удорожает развитие программы.»
Если в документации написано про одно и то же в нескольких местах, можно сказать, что документ плохо структурирован или вычитан. И речь не про дублирующие части, которые нужно выносить в отдельные файлы и встраивать их в другие страницы.
В документации почти каждый текст может оказаться утяжелителем изменений, и этого не избежать. Функциональность каждого продукта со временем меняется, и любое изменение функциональности продукта меняет документацию. Не важно, что поменялось: название, настройки, ссылки или функции. Нужно обновить везде, где они используются. К тому, что документация развивающегося продукта быстро устаревает, нужно привыкнуть.
К документации в крупных компаниях относятся как к продукту, который живёт и изменяется по своим правилам. Взгляд технического писателя на документацию со временем меняется, как и правила, которым технические писатели следуют. Это идёт на пользу документации, потому что делает её понятнее и предсказуемее для пользователя.
Замусориватели
«Замусориватели являют собой что-то бесполезное и лишнее, от чего можно было бы избавиться, сделав код чище, эффективней и проще для понимания.»
Здесь будет немножко инфостиля, уж простите. В технической документации (я не говорю про ту, что написана по ГОСТ) не место стоп-словам. Главред под ними понимает:
Я бы ещё добавила в этот список жаргонизмы и сленг. Всё это делает текст двусмысленным, грязным и неконкретным. Обращайте внимание на те слова, которые вы используете при написании документации. Заводите правила на стоп-слова в вашей компании.
Опутыватели связями
«Все запахи из этой группы приводят к избыточной связанности между классами, либо показывают, что бывает, если тесная связанность заменяется постоянным делегированием.»
Такое возникает в документации, когда для создания/настройки одного объекта нужно выполнить создание/настройки других объектов. Продукт может относиться к сложной предметной области, в которой подобных цепочек не избежать. Это не исправляется на уровне документации. Всё, что вы можете сделать, — это описать правильную последовательность шагов по настройке и возможные трудности, с которыми может столкнуться пользователь.
При этом нужно понимать, что документация настроек может содержать:
дублирующие части, когда какие-то настройки нескольких продуктов совпадают;
перекрёстные ссылки на документацию отличающейся настройки других продуктов.
В случае дублирующих частей документации их нужно по мере необходимости выносить в отдельные файлы и встраивать их в другие страницы. Если же документация настройки отличается, то хорошим решением будет добавление в текст перекрёстных ссылок.
