Привет, Хабр! Пришла делиться новыми статьями, ведь как доклады они не интересны. Буду вещать про связь программирования и технической документации (как обычно), только смещу фокус с похожести на применяемость одного в другом.
Выше я лишь намекнула, о чем пойдет мой разговор, сейчас я распишу подробнее. Часто подход к разработке документации Docs as code воспринимается как что-то тяжеловесное, неповоротливое, сложное и даже страшное. Я постараюсь развеять это мнение или хотя бы повлиять на него. В одну статью я не уложилась, когда писала черновики, поэтому в этой статье я расскажу о существующих подходах к разработке документации (иногда негласных, но все-таки существующих), их особенностях, преимуществах и недостатках. В следующих статьях я расскажу про более практическую часть и использование Docs as code. Держитесь!
Все определения не являются цитируемыми определениями. Они заключены в кавычки, чтобы выделить их в тексте.
Подходы к разработке технической документации
Моим большим упущением с начала публикаций было то, что я не подсветила, что говорю только о продуктовой документации. И сейчас я буду говорить тоже только о ней. Это, конечно, не исключает ситуации, что эти подходы можно применить и к другой документации, но мне кажется, что по крайней мере первые два используются там реже.
К основным подходам относятся:
Single-source publishing, или принцип единого источника.
Docs as code, или документация как код.
Knowledge bases, или базы знаний.
Files, или файлы (не являются официальными названиями).
Сначала рассмотрим суть каждого из подходов и их особенности, а сравнительный анализ оставим напоследок.
Single-source publishing
«Single-source publishing (принцип единого источника, публикация из единого источника) — это концепция публикации документов, согласно которой один и тот же контент может быть использован в разных документах или в разных форматах.»
Основные положения подхода:
Write once, publish everywhere.
Одна точка входа для изменений.
Генерация документации в разных форматах из исходных файлов.
Такие определение и положения можно встретить повсеместно в интернете. Я понимаю этот подход шире.
«Single-source publishing — это подход к разработке технической документации, когда единственный инструмент отвечает всем задачам жизненного цикла документации.»
Таким образом, мы имеем готовое решение, которое удовлетворяет требованиям:
Публикация одинакового контента в нескольких источниках.
Импортирование файлов разных форматов (HTML, XHTML, DOC, DITA, Help projects).
Распространение документации в форматах:
Веб-приложений (HTML5, XHTML).
Печати (PDF, DOC).
Настольных приложений (HTML Help, JavaHelp, RTF, DITA).
Мобильных приложений (eBook).
Редактирование документации в пределах проекта несколькими авторами.
Наличие ролевой системы.
Имеется пользовательский интерфейс как у продвинутого графического текстового редактора.
Поиск по контенту.
Является системой управления контентом.
Это не все, но это основная часть. Грубо говоря, технический писатель вошел в систему и не вышел, пока не переделал все задачи.
Knowledge bases
«Knowledge bases (базы знаний) — это концепция ведения и управления важной информацией компании в инструментах по типу справочного центра.»
Основные положения подхода:
Использование инструмента по типу справочного центра.
Создание и поддержка логичной и понятной структуры разделов.
Регулярное обновление через определение ответственных за контент.
Улучшение через сбор обратной связи.
Этот подход имеет более широкую направленность и аудиторию. Исходя из того, что инструменты баз знаний имеют встроенный графический текстовый редактор, они проще в использовании. Для управления страницами, разделами и всем инструментом есть понятные роли и права пользователей. Почти все выполняется по нажатию кнопки.
Files
«Files (файлы) — это концепция ведения научных публикаций, документации и другого текстового контента в графических текстовых редакторах, направленных на редакторскую работу с текстами и другим визуальным контентом.»
Самый негласный подход, который до сих пор существует. Один раз настроил стили, макросы и структуру отдельных документов в Microsoft Word, а потом используешь эти надстройки через создание копий этих документов.
Сейчас существуют и другие инструменты (под другие ОС, например), но отличает эти инструменты именно профессиональные функции и такой же профессиональный уровень пользователей, которые их используют. Сколько споров было разожжено из-за колонтитулов или ссылки на изображения!
Docs as code
«Docs as code (документация как код) — подход, согласно которому создание документации выполняется с помощью тех же инструментов, что и создание программного кода.»
Подход в свое время описали аж два человека: Энн Джентл (Anne Gentle) и Эндрю Эттер (Andrew Etter).
Основные положения подхода (из книги «Docs like code»):
Храните исходные файлы документов в системе контроля версий.
Создавайте артефакты документации автоматически.
Убедитесь, что надежная команда рецензентов тщательно проверяет документы.
Публикуйте артефакты документации без особого вмешательства человека.
Таким образом, нам необходим инструмент для работы с документацией, где мы:
Применяем сценарий жизненного цикла ПО к процессу создания документации.
Разрабатываем документацию по гибким методологиям, как и ПО.
Для создания документации используем технологии и инструменты разработки ПО.
Я специально оставила этот подход на конец, ведь теперь видна ключевая разница между подходами. А именно: мы сами определяем инструменты и их вид и функциональность. Определяем большую часть из этого, конечно, так как у компании уже есть технологический стек, бюджет и другое. Но многие инструменты — это open-source, и их можно переписать или дописать. Выбор ваш.
Преимущества и недостатки подходов
Сейчас можно поговорить о том, что же хорошего, а что плохого несет каждый из подходов. Теперь подход Docs as code встанет обратно на вторую позицию в повествовании.
Single-source publishing
Преимущества
Переиспользование контента.
Снижение ошибок в контенте за счет переиспользования.
Консистентность в стилях документов.
Не требует ресурсов на разработку отдельного инструмента.
Недостатки
Распространяются только на платной основе.
Высокий порог вхождения.
Доступно в основном только для Windows.
Ограниченная функциональность, фича-реквесты могут не сработать.
Docs as code
Преимущества
Вовлеченность технических писателей в процессы создания ПО.
Вовлеченность разработчиков в процессы создания документации.
Автоматизация процессов документирования.
Гибкость функциональности за счет open-source.
Недостатки
Высокий порог вхождения.
Необходимость ресурсов разработки.
Допуск технических писателей к кодовой базе.
Knowledge bases
Преимущества
Возможно переиспользование контента.
Низкий порог вхождения.
Недостатки
Иногда распространяются только на платной основе.
Ограниченная функциональность, о фича-реквестах можно забыть.
Files
Преимущества
Мощный редактор.
Доступность.
Узнаваемость.
Применяемость.
Недостатки
Может потребоваться разработчик для своего макроса.
Несовместимость версий ПО.
Иногда несовместимость при использовании разного ПО для одного и того же документа.
Заключение
Когда мы рассмотрели основные подходы, можем выделить типы задач, для которых каждый из них подходит лучше всего. Определенно, это деление не панацея, и всегда будут исключения, но такое обобщение допустимо.
Критерии деления:
Целевая аудитория документации.
Открытость или закрытость документации для аудитории.
Направленность документации.
Количество документации.
Количество ресурсов на поддержку документации.
Специфика к типографике документации.
Порог вхождения для поддержки документации.
Задача/требование | Single-source publishing | Docs as code | Knowledge bases | Files |
Документация для разработчиков: API, CLI | + | + | — | — |
Документация для разработчиков: SDK | — | + | — | — |
Внешняя публичная продуктовая документация | + | + | — | — |
Внешняя приватная продуктовая документация | + | + | + | — |
Внутренняя продуктовая документация | — | — | + | — |
Внутренняя не техническая документация | — | — | + | — |
Внешняя или внутренняя продуктовая документация без ресурсов на системность и автоматизацию | — | — | + | + |
Небольшой поток документации | — | — | + | + |
Большое количество специфических требований к документации в целом или к отдельным ее частям с малыми ресурсами на поддержку | — | — | — | + |
Большое количество специфических требований к документации в целом или к отдельным ее частям с большими ресурсами на поддержку | + | + | — | — |
Низкий порог входа в создание документации | — | — | + | ± |
Все задачи объять невозможно из-за специфики каждой отдельной команды или компании, но поверхностно я попыталась их покрыть.
В следующих статьях буду говорить только о подходе Docs as code. Часть 2 заденет конкретные решаемые этим подходом задачи и ключевые аспекты к его пониманию, а в части 3 опишу шаблоны по работе с инструментами для разной документации в этом подходе.
