Документирование сегодня - технологии и тренды

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

Прежде всего, “документирование” - это уже давно не только про документацию, и технический писатель сегодня чаще всего работает не просто с документами, а с контентом. Глобально этот контент можно разделить на:

• внешний - контент для пользователей, клиентов;
• внутренний - база знаний, заметки, документация для сотрудников компании и команды разработки.

При этом контент - это не только текст! Это комиксы, гифки, скринкасты, онлайн-курсы, подсказки, видеоуроки и т.д.

(c) Randall Munroe, source

Контент для клиентов

Внешний контент - это то, что читают, смотрят и слушают клиенты. Наверное, вы думаете, что тут самое важное что-то вроде Руководства пользователя? А вот и нет. Вы сами-то когда инструкцию последний раз открывали (про лицензионное соглашение я вообще молчу)?

Приоритеты в отношении важности контента можно наблюдать на примере публичных материалов компании. Например, IBM, VMware, Huawei (их документацию я читаю очень часто). Видно, что:

• база знаний по ошибкам и troubleshooting обновляется буквально каждый день (скорее всего - инженерами технической поддержки и техническими писателями/аналитиками);
• онлайн документация часто отстает от версии ПО (на сайте IBM в последней версии доки очень долго висело старое описание архитектуры ПО, там уже нет давно этих компонентов);
• PDF обновляется реже или по запросу (например, у Huawei pdf могут отличаться от онлайн-документации).

Основные проблемы внешнего контента:

• проклятие знания - описания составляются людьми, которые “в теме”, и им сложно представить, что пользователь может споткнуться на первом же пункте их инструкции;
• неактуальность - бытует мнение, что неактуальное описание еще хуже, чем его отсутствие. Припоминать IBM их неактуальное описание архитектуры буду до конца жизни;
• too long didn’t read/couldn’t find - слишком сложный, плохо структурированный текст и отсутствие поиска (не упомянуты ключевые слова, не проиндексирована база - статья есть, но пользователь просто не смог ее найти).

Вот примерный перечень “маст-хэв” контента для большинства компаний в порядке приоритета.

UI text

Первый рубеж обороны: тултипы (подсказки), встроенная умная справка (динамические пояснения, которые, например, появляются при заполнении формы), человеческие сообщения об ошибках, логичные надписи на кнопках. Да, всё это пишут UI writers, которые тусят в отдельной ветке репозитория, чаевничают с дизайнерами, а зачастую - совмещают роль UI/UX designer и UI writer.

Сейчас это направление активно развивается во всех софтварных и не только компаниях. Например, всё новое ПО Adobe снабжено краткими туториалами и пояснениями к инструментам с всплывающей демонстрацией прямо в интерфейсе. А новые принтеры Canon, снабженные небольшим дисплеем, дают советы и подсказки в процессе работы (какую кнопку нажать, как исправить ошибку, что куда вставить).

Пример:

Troubleshooting

У пользователя возникает мысль: “А не заглянуть ли мне в документацию?” чаще в тех случаях, когда что-то работает не так, или у него не получается это что-то сделать. И даже тогда, он предпочитает спросить у соседа или погуглить. А особо упорные (например, бизнес-пользователи) еще и звонят в техподдержку. И вот тут самым важным контентом становится база знаний по проблемам. К наполнению базы так или иначе прикладывают руку все - инженеры поддержки, технические писатели, разработчики, администраторы, аналитики, и даже юристы. А чтобы всё это было просто найти - SEO-оптимизаторы и прочие интернет-кудесники.

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

Пример.

Reference

Справочник по командам (console command reference), документация на API. Это специфическая документация, которая так или иначе генерируется на основе исходного кода (из комментариев, спецификаций), дополняется техническим писателем, разработчиками и публикуется при сборке проекта. Разрабатывают эту доку элита техписательского мира - API writer. Эти товарищи не просто могут разобраться в коде и его закомментировать, но и сами проектировать API.

Пример. Еще пример.

User documentation

Наконец-то, добрались. Пользовательская документация - это руководства, инструкции, “быстрые старты”, схемы и пр. Это документация, которая должна быть симпатичной, и максимально доступно (с учетом целевой аудитории) рассказывать о фичах продукта и помогать в его использовании. В разработке документации есть несколько принципов:

• KISS - keep it simple (stupid) - если описание какой-то операции получается слишком сложное, то возможно проблема не в описании, а в самом процессе работы;

• YAGNI - you aren’t gonna need it - часто хочется задокументировать прям вообще все. Это ловушка, в которую легко залезть и очень сложно выбраться (и затратно), поэтому всегда надо учитывать целевую аудиторию и то, вообще зачем нужен ваш продукт. Вот точно нужно описание вот этого алгоритма в доке? Возможно, стоит оставить его во внутренней вики.

Этот контент - основной хлеб и боль технического писателя. Однако и тут есть новомодные ответвления. Чтобы всю это документацию грамотно написать, выбрать инструменты, настроить git, настроить шаблоны, сделать все эти красивые сайтики и pdf-ки, тоже нужно как следует поработать.

Этим занимаются DocOps-инженеры, программисты, самоучки, которые всю эту инфраструктуру могут настроить. Они знают python, не боятся XSLT, спят с гайдом Latex под подушкой и могут за пару часов поднять симпатичный сайт с вашей докой.

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

Онлайн-курсы и туториалы

Если продукт достаточно специфичен и компания заинтересована, в том, чтобы пользователи все делали сами (актуально для self-service продуктов), то курсы и туториалы - то, что доктор прописал.

Курсы могут быть набором презентаций, полноценной онлайн-платформой, набором видео-уроков, с тестами, сертификатами и т.п. Онлайн-курсы, как правило, разрабатываются на основе документации с учетом реальной практики применения (ну или наоборот, документация разрабатывается по онлайн-курсам :)). Информация должна быть отлично структурирована, снабжена примерами, не должно быть ничего лишнего - поэтому онлайн-курс по сложности подготовки выше, чем просто пользовательская документация. Документация - тебя кинули в воду и дали жилет, ну и ты там как-нибудь плыви, онлайн-курс - тебе дали катер и маршрут.

Пример - видео-инструкции по часто задаваемым вопросам. Пример портала VMware.

Use-case и best practice

Лучшие практики, white papers и т.п. могут разрабатываться не самой компанией, а многочисленными пользователями (блоги, how-to, статьи на хабре) или партнерами (IBM Best Practises, например). Этим контентом управляют разнообразные контент-менеджеры, которые следят за такими статьями в интернете (ну, если у компании есть такая политика). Это можно наблюдать, например, когда под какой-то статьей how-to на хабре появляется разработчик или представитель компании, и начинает отвечать на вопросы или давать пояснения.

Use-case сейчас уже стараются разрабатывать и сами компании. Например, редактор OxygenXML в своей документации публикует конкретные примеры источник которых - вопросы пользователей и форум. Это, собственно, единственное, для чего я использовала их документацию.

Контент для сотрудников

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

Основные проблемы внутреннего контента:

• проклятие знания - но в другом смысле. Во многих компаниях сталкиваются с тем, что сотрудники не пишут или не пользуются базой знаний, просто потому что …. не умеют! Да, им никто не показал, как, например, эффективно искать, правильно писать (отсутствуют шаблоны и примеры), как создавать ссылки и т.д. Так что имеет смысл все это показать при онбординге на проект. К тому же часть сотрудников боятся писать (“я не умею писать, я плохо пишу”) или не понимают, зачем оно им (“я программист, я что должен писать какой-то текст прям словами?! О_О”) - с этим тоже надо работать;
• дублирование - я вот сейчас что-то узнал, быстренько пойду запишу в вики. А потом бедный технический писатель заходит, ищет в поиске - и находит 3 версии одного и того же с сомнительной актуальностью;
• неактуальность - добавили фичу, поменяли алгоритм - а статью вики не обновили. Или побежали написали новую статью (см. выше). Технический писатель психанул и ушел в запой (true story).

Вот несколько примеров внутреннего контента.

Troubleshooting

Troubleshooting - база знаний технической поддержки. И тут она в первых рядах.

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

Visions and algorithms

Visions and algorithms - описания разной степени детализации, концепция, архитектура, описания алгоритмов, исследования, причины принятых технических решений, диаграммы и схемы. Все, что поможет и старым, и новым сотрудникам понять, что вообще происходит с проектом, почему выбрано это архитектурное решение и как с этим жить.

Onboarding

Onboarding guide. Контент для обучения и адаптации новых сотрудников. Onboarding - это остальные 50% докладов по управлению знаниями и командами. Сюда входят общие гайды (как написать заявление, где взять шаблон, как оформить ДМС) и проектные гайды (о чем проект, кто за что отвечает, где тут репозиторий, какой код за что отвечает, где ТЗ, гайдлайны, шаблоны оформления задач и т.п.).

Root Cause Analysis

Root Cause Analysis. Невероятно важный документ в инфраструктурных компаниях. Этот отчет, которые составляют понемногу все (чаще инженеры и аналитики) по результатам аварии, нескольких аварий, серьезных сбоев в работе и т.п. Отчет включает разбор источника проблемы (root), причин (causes), описывает, как проблему решили (или почему не решили) и перечисляет действия, чтобы сбой не повторялся. Формат отчета может быть разным (от коммента к задаче до серьезного отчета на красивых страницах с графиками).

QA texts

Тестировщики тоже много пишут. Часто именно их тексты становятся основой для разработки пользовательской документации. Тестировщики пишут описания шагов воспроизведения ошибок, описания use-case, отписываются в задачах, пишут в вики (чтобы с миром поделиться и самим не забыть).

К сожалению, не сразу приходит понимание, что весь этот контент - тоже очень ценен и на его разработку тратится уйма времени. Чтобы сократить это время внедряют системы управления тестами (чтобы не писать сочинения в задачах, а более-менее их формализовать).

Инструменты

Люди вообще довольно ленивые существа, поэтому стремятся упростить себе жизнь, поэтому изобретают всякие инструменты себе в помощь. Правда, иногда это оборачивается тем, что времени и денег приходится тратить еще больше, поэтому всегда важно подобрать правильный инструмент для задачи. Например, если требуется разработать маленький документ, типа регламента, с кучей разнообразных комментирующих и согласующих из разных отделов - вероятно не стоит городить огород с git и markdown и проще всего будет использовать Word или Google Docs.

Интересный блог: idratherbewriting от технического писателя из Amazon. Пишет про всякие инструменты, практики и общие мысли о документировании вообще.

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

Текстовые процессоры

Наше все Microsoft Word, Libre Office, а также, например, Google Docs и всякие похожие на Word онлайн-редакторы и внезапно верстальные программы (например, Adobe Indesign). В общем, это программы (локальные или облачные), которые представляют собой редактор типа WYSIWYG (What you see is what you get - что видишь, то и получишь).

Основные преимущества (их еще называют “трясина Microsoft Word”):

• очень низкий порог вхождения и простая поддержка (не надо человека учить, низкие затраты на поддержку, отредактировать может любой);
• просто сделать нестандартное оформление (например, чередование альбомных и портретных страниц, рамки, сложные таблицы с объединенными ячейками, сноски, списки (типа библиографии), автоматическая нумерация и ссылки);
• не нужно париться насчет шаблонов, что нарисовал в документе - то и получилось в pdf;
• распространенность (с вероятностью 99% любой заказчик/клиент или коллега сможет открыть docx/rtf/odt в любом, даже онлайновом, редакторе).

Недостатки:

• не получится хранить под версионным контролем, например, в git, чтобы отслеживать изменения;
• из выходных форматов по сути только pdf, для веб придется использовать другой инструмент и переносить текст руками;
• среда разработки и среда документирования “разделена”, что уменьшает вовлеченность команды;
• оформление привязано к контенту, не получится менять оформление быстро (даже со стилями);
• открыть документ можно только специальным редактором (онлайн или локально), просто в блокнотике не посмотришь - нечитаемый исходник;
• косяки, которые всплывают при работе с большими документами, и просто иногда word/libre office бесят;
• нет или трудно сделать переиспользуемые блоки текста, что увеличивает время на переработку похожих документов.

Единый источник

Этот подход можно было бы включить, например, в Doc As Code, но у него есть кое-какие особенности, и поэтому я вынесла его в отдельную категорию. Single source, или “единый источник”, подразумевает постоянное переиспользование текстовых файлов и блоков. То есть весь текст хранится в отдельных файлах, результирующий документ “собирается” из подлинкованных файлов. Соответственно, один и тот же файл или блок текста можно использовать много раз в разных документах и изменять одновременно везде.

Существует несколько реализаций этого подхода, самые распространённые из которых DITA, Docbook, основанные на них ответвления и несколько инструментов. Под капотом и у DITA, и у Docbook - xml. Инструменты:

• OxygenXML - самый дешевый инструмент для работы с xml-форматами. Из коробки поддерживает несколько шаблонов для html/pdf. PDF-процессор поддерживает кастомизацию .CSS, что позволяет реализовать любое оформление для pdf;
• Adobe Framemaker - большая, тяжелая, дорогая прога от Adobe. Использует некоторые наработки Indesign, так что, вероятно, удобно использовать для сложных каталогов, брошюр и информационных буклетов;
• MadCap Flare - дорогущая махина, которая может все. Я как-то поставила и попробовала. Да, возможности огромные, но цена неадекватная.
• AuthorIT - набор программных решений для публикации документов. С упором на командную работу (хотя все так или иначе их поддерживают). Цена - несколько тысяч долларов.

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

Недостатки:

• (очень) дорого;
• основные инструменты (Docbook, DITA) сами по себе opensource, однако требуют высокой квалификации, чтобы из всего этого добра собрать рабочий workflow. И редакторов хороших бесплатных все равно нету;
• привязка к редактору (часто платному), так что не получится быстренько посмотреть и отредактировать исходник коллеге.

Достоинства:

• можно сделать какой угодно красивый PDF со сложными схемами, листами, рамками и штампами;
• переиспользование текста.

Вики

Этот подход - нечто среднее между текстовыми процессорами и Doc As Code. Реализовано, как правило, как некая вики-система - самая распространенная Jira/Confluence или какой-нибудь Redmine - в которой пишут доку в онлайн-редакторе (WYSIWYG или язык разметки). Часто эта вики и есть документация, которая доступна пользователям, и дополнительные операции по выводу доки уже не нужны. Можно переиспользовать блоки текста (не во всех wiki-системах).

В некоторых wiki-системах исходник текста хранится под версионным контролем в репозитории, что позволяет далее использовать инструменты Doc As Code для генерации html/pdf. Также есть маленькие вики-системы, вроде DokuWiki, которые можно запускать прямо с флешки и исходные тексты хранятся в обычных текстовых файлах.

Преимущества:

• низкий порог вхождения;

• участвует вся команда;

• можно использовать для внутренней или для внешней документации.

Недостатки:

• красивый вывод в pdf трудно настроить и поддерживать;
• при отсутствии организации - очень быстро скатывается в хаос, разброд и шатание. Выражается в дублировании статей, неактуальными статьями и отсутствием вменяемых search-friendly названий.

Doc from Code

Doc from Code, или “документация из кода”, объединяет инструменты, которые позволяют полностью или частично генерировать документацию из кода программы. В эту категорию входят:

• генерация документации на API - Swagger, WSDL и аналоги. В коде в особом формате записываются комментарии или указатели, из которых затем генерируется либо готовая документация либо файл-“спецификация”, который можно уже доводить до ума вручную (или не доводить, а использовать прям так);
• генерация документации из кода по комментариям или без них - javadoc, dokku и другие для конкретного языка программирования. Комментарии записываются в специальном формате, которые затем автоматически собираются инструментом;
• генерация схем из кода - для этого используются разнообразные плагины или средства среды разработки. Результирующая диаграмма зависит от кода и его сложности, не всегда можно сгенерировать что-нибудь полезное;
• генерация документации на БД - натравливаешь документатор на БД - и тебе выдают красивый сайт или pdf с описанием (конечно, если это описание есть в БД… например, в комментариях).

Преимущества:

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

Недостатки:

• инструменты документирования API лучше планировать на старте разработки, прикручивать потом - несколько сложнее;
• требуется время и усилия разработчиков на написание и поддержание хотя бы минимального количество документации в коде/комментов в базе.

Doc As Code

Стильный модный молодежный подход, на который так или иначе переехали или пытаются переехать софтварные и не очень компании. В основе философии Doc As Code:

• разделение текста и оформления - тут как в Single Source подходе. Текст набирается на одном из языков разметки, оформление “цепляется” любым удобным способом;
• хранение текста в репозитории рядом с кодом;
• включение процесса “сборки” документации в процесс сборки проекта (ci).

Для разработки документации используются программы, похожие на среды разработки программистов (также можно писать прямо в этой среде, есть плагины) с возможностями WYSIWYG. Редакторы, типа Typora, VS Code и тысячи их, также могут показывать, как будет выглядеть текст, выводить простенькие html и pdf и импортировать текст, например, из Microsoft Word.

Преимущества:

• удобно для разработчиков, проще подключить членов команды к документированию;
• версионный контроль - это очень удобно;
• можно настроить множество выходных форматов - pdf, html, хэлпы;
• легко менять оформление, не меняя текст;
• встраивается в процесс сборки проекта, среды документирования и разработки не разделены;
• можно сделать single source;
• удобно делать локализацию (актуально для мультиязычной документации).

Недостатки:

• затраты на поддержку инфраструктуры - кто-то должен разрабатывать шаблоны, настраивать pipeline для сборки документов, допиливать плагины;
• средний порог вхождения для разработки, собственно, доки, высокий порог - для поддержки;
• языки разметки сами по себе достаточно ограничены, поэтому их приходится допиливать плагинами, дополнениями и “костылями”;
• pdf. Кажется, разделение кода и оформление не должно вызывать проблем с выводом pdf, а оно вот так. Нет, стандартный pdf вывести не проблема, а вот если вам (внезапно!) нужны списки по простенькому гост, надписи в колонтитулах, рамки, таблички и альбомные страницы - то тут-то и выясняется, что нормальных pdf-процессоров раз два и обчелся, и каждый первый - через latex (второй через docbook), и с каждым еще надо плясать с бубном. Сейчас ситуация уже не такая плачевная, как пару лет назад (например, для asciidoctor добрые люди поделились шаблоном).

Подробнее с примерами про подход DocAsCode можно прочитать в недавней статье на Хабре. А поговорить об этом можно в чате: https://t.me/docsascode.

Языки разметки

Языков разметки для использования в Doc As Code нынче наплодилось много, однако самые распространенные вот такие:

Markdown и разнообразные его “flavors”, расширяющие возможности базового языка. Markdown, пожалуй, самый распространенный язык разметки, который используется практически во всех вики, репозиториях (git, gitlab) и баг-трекинговых системах (jira, youtrack). Очень простой в изучении, невероятное количество редакторов, зашкаливающее множество плагинов и расширений. Недостатки: очень простой (без плагинов), таблицы, с pdf отношения по-прежнему напряженные (хотя сейчас уже ситуация получше).

restructeredText - язык разметки посерьезнее, со спецификацией. Много чего поддерживает “из коробки” - нумерацию, сноски, списки, более-менее приличные таблицы и т.д. Как инструмент для компиляции часто использует sphinx, а для разработки расширений - python, что упрощает допиливание собственных плагинов. С выводом в pdf как у всех языков разметки - так себе.

ASCIIDoc/ASCIIDoctor - в узких кругах сектантов DocAsCode считается вершиной эволюции языков разметки. Конкурирует с restructeredText по функциональности. Дружит с разнообразными reveal.js. Мега-удобно создавать одностраничные веб-хелпы и красивые pdf (где нет требований жестких к ГОСТ), есть красивый редактор AsciidocFX - установил и пользуйся сразу. Есть вывод в pdf с помощью asciidoctor-pdf. Можно прикрутить красивый вывод в ГОСТ (с рамками и всеми делами) через шаблон. Набирает обороты разработка asciidoctor-web-pdf, так что светлое будущее уже почти наступило;

LaTeX - старый добрый LaTeX, который активно используется в академической среде. Может всё, а что не может, это значит вы просто не знаете как. Высокий порог вхождения, но если уж разобрался как прикрутить клятые шрифты, рамки и альбомные листы - можно собрать, что угодно. Идеально подходит для работы с научными статьями, отчетами и формулами.

Генераторы

Текст мы на языке разметки написали, теперь надо превратить текст в красивый PDF или сайт с документацией. Для этого тоже существует множество инструментов и утилит, хотя под капотом у них достаточно ограниченный набор одних и тех же программ - pandoc и latex-компиляторы/процессоры или xslt-процессоры. Последние несколько лет также появляются утилиты на JavaScript (HML + CSS > PDF), так что возможностей становится всё больше.

Процессоры. Честно говоря, чистые процессоры встречаются редко, обычно они используются в составе генераторов или инструментов “все-в одном”. Например, для docbook используется процессор Apache FOP.

Генераторы статических сайтов. Это набор утилит и скриптов, которые берут контент из текстовых файлов, парсят язык разметки, прикручивают выбранную тему оформления/css и выдают статический сайт - html, js, css - можно сразу же загрузить на веб-сервер или положить в гит-хаб. Таких генераторов нынче очень много, самые известные в документаторской среде - Hugo и используемый GitHub - jekyll.

Всё в одном. Набор разнообразных opensource утилит, объединенных и доведенных до ума. От пользователя обычно требуется установить и запустить какую-нибудь простенькую команду - и вот вам готовый сайт/pdf. Примеры:

• Asciidoctor - всё в одном для генерации документов из asciidoc формата. Расширяется плагинами, например, для вывода в pdf;
• Sphinx-doc - генератор доки для restructeredText;
• Foliant - инструмент, на который я с интересом смотрю, но пока не пробовала. Говорят, даже pdf с css нормальный есть;
• Mkdocs + WeasyPrint - популярный сайт документации на markdown. Расширяемый за счет огромного количества плагинов.

Вот и все, что я могу сказать по этому вопросу (с). Счастливого плавания и такие дела :)