Иногда команды сталкиваются с нехваткой технических писателей, когда задокументировать нужно много, а ресурсов не хватает. Не все рядовые технические писатели могут быстро понять код и описывать процессы, не прибегая к помощи разработчиков.
В таких случаях команда может документировать процесс сама, но технический писатель может упростить эту задачу — рассказать разработчикам, как лучше писать документацию, какие шаблоны и приёмы использовать. И для этого подойдут шаблоны и приёмы с аналогами в разработке. Их разработчики смогут понять и использовать.
В моей предыдущей статье Запахи технической документации я писала про схожесть применяемых способах познания программирования по отношению к документации. Что я сделаю сейчас? Совершенно то же самое. Напомню, что шаблоны проектирования описывают типичные способы решения часто встречающихся проблем при проектировании программ. Рассмотрим шаблоны проектирования, представленные на ресурсе Refactoring Guru (сейчас он запрещен на территории РФ). Ну, что, начнем?
Порождающие шаблоны
Беспокоятся о гибком создании объектов без внесения в программу лишних зависимостей.
Фабричный метод
«Определяет общий интерфейс для создания объектов в суперклассе, позволяя подклассам изменять тип создаваемых объектов.»
Это похоже на переиспользование контента:
Выбираем максимально одиночное описание функциональности.
Выносим это в отдельный раздел.
Используем во всех местах, где встречается.
Это может быть преднастройка, общее начало по типу «зарегистрируйтесь» или «авторизуйтесь».
Абстрактная фабрика
«Позволяет создавать семейства связанных объектов, не привязываясь к конкретным классам создаваемых объектов.»
Это похоже на переиспользование структуры описаний, их единообразие:
Делим описание разных функциональностей на разделы, которые могут быть общими для всех функциональностей. Каждый такой раздел должен использоваться как минимум в одном разделе более верхнего уровня.
Используем во всех местах, где встречается.
Чаще это используется в документации SDK, API, где есть либо версии, либо функциональность, которая повторяется для каждого языка программирования.
Строитель
«Позволяет создавать сложные объекты пошагово. Строитель дает возможность использовать один и тот же код строительства для получения разных представлений объектов.»
Это похоже на сущности документирования, предложенные Даниэлем Прочида (компания Divio) в 2017 году на PyCon Australia. Мы возьмем только два из них для понимания шаблона:
Tutorials — туториалы/getting started/quick start.
How-to guides — инструкции.
Алгоритм следующий:
Вы создаете инструкции на всю функциональность. Точечные пошаговые описания.
Вы создаете туториал на каждый законченный сценарий использования продукта. Каждый туториал состоит из нескольких инструкций.
Таким образом мы имеем уникальные инструкции и туториалы, которые можно «собирать» из разных инструкций под разные нужды.
Прототип
«Позволяет копировать объекты, не вдаваясь в подробности их реализации.»
Это похоже на использование шаблонов видов документов, их единообразие:
Вы определяете шаблонную структуру каждого вида документа.
При создании нового документа вы используете заготовленную структуру.
Это помогает держать документацию однообразной. Когда вы используете шаблоны структуры, пользователь при чтении документации будет примерно понимать, что ждать от каждого раздела. Шаблоны структуры также помогают техническим писателям понять, что именно требуется для каждого типичного вида документа.
Одиночка
«Гарантирует, что у класса есть только один экземпляр, и предоставляет к нему глобальную точку доступа.»
Это похоже на переиспользование контента в технической части:
Выносим все необходимые повторы в одно специальное место.
Используем во всех местах, где встречается.
Чаще всего это общие части, которые необходимы для нескольких разделов.
Структурные шаблоны
Показывают различные способы построения связей между объектами.
Адаптер
«Позволяет объектам с несовместимыми интерфейсами работать вместе.»
Это похоже на использование других сущностей документирования:
Tutorials — туториалы/getting started/quick start.
How-to guides — инструкции.
Reference — справочники.
Как это работает:
У вас есть информация, которая необходима для инструкций или туториалов. Но она напрямую не связана с выполнением конкретных шагов этих инструкций.
Тогда вы создаете отдельные страницы Справочника и ссылаетесь на него из инструкций и туториалов.
Мост
«Разделяет один или несколько классов на две отдельные иерархии — абстракцию и реализацию, позволяя изменять их независимо друг от друга.»
Это похоже на выделение из справочной информации каких-то глубинных вещей и использование этих вещей в других местах справочника. Давайте разберем пример:
У нас есть фильтры.
Фильтры содержат поля. Разные фильтры могут состоять из одинаковых полей.
Алгоритм следующий:
Вы выделяете поля в отдельный раздел.
В каждом фильтре вы ссылаетесь на раздел с полями.
Компоновщик
«Позволяет сгруппировать множество объектов в древовидную структуру, а затем работать с ней так, как будто это единичный объект.»
Это похоже на дерево решений в документации. А точнее, это отображается как два (или больше) вложенных элемента вкладок на сайте документации. При выборе каждой вкладки контент уточняется в соответствии с ними.
Декоратор
„Позволяет динамически добавлять объектам новую функциональность, оборачивая их в полезные «обертки».“
Это также похоже на переиспользование контента, о котором мы говорили в Фабричном методе.
Фасад
«Предоставляет простой интерфейс к сложной системе классов, библиотеке или фреймворку.»
Это также похоже на туториалы и инструкции. Инструкция — фасад, а разные туториалы — конкретные реализации функциональности.
Легковес
«Позволяет вместить бóльшее количество объектов в отведенную оперативную память. Легковес экономит память, разделяя общее состояние объектов между собой, вместо хранения одинаковых данных в каждом объекте.»
Шаблон наталкивает на два понимания применительно к документации:
Объем в знаках. Но у нас нет необходимости писать в стиле снижения количества знаков и слов. Мы наоборот знаем, что в документации нет смысла сокращать. Все должно быть понятно с первого раза.
Лаконичность и консистентность. Несмотря на то, что мы не задумываемся о количестве «отпечатанных» знаков, мы заботимся о том, чтобы терминология и качество документации оставались четкими на высоком уровне. «Много знаков» не означает «хорошая и понятная документация».
Заместитель
«Позволяет подставлять вместо реальных объектов специальные объекты-заменители. Эти объекты перехватывают вызовы к оригинальному объекту, позволяя сделать что-то до или после передачи вызова оригиналу.»
Очень похоже на использование языков разметки в любом виде в подходах Docs as code и Single-source publishing. Текст в языке разметки будет считаться «объектом-заменителем», а текст в HTML — «реальным объектом».
Поведенческие шаблоны
Эти шаблоны не совсем соотносятся с документацией. Может быть применительно к инструментам документации. Но об этом — в другой раз.
