- А как вы поддерживаете справку по API в актуальном состоянии?
- Как можно организовать и хранить локализованные версии?
- Вы проверяете текст на наличие недопустимых символов и на валидность разметки?
- Как организовать проверку (вычитку) топиков?
Эти и другие вопросы я часто слышу от технических писателей на конференциях. Для небольших объёмов документации достаточно вручную пересмотреть документы и обновить/подставить/поправить всё, что нужно. А если объёмы документации выросли?
Наша документация выросла до более чем 154 000 документов только по .NET-линейке продуктов, из них около 140 000 документов — это справка по API. Около 8-10 тысяч топиков добавляются каждый мажорный релиз (т.е. дважды в год). В этой статье я расскажу как мы справляемся с такими объёмами.
Здесь я не приведу названия общедоступных инструментов, потому что всё, что мы используем — это самописные приложения и сервисы, которые глубоко интегрированы в нашу инфраструктуру и слабо применимы вне её. Поэтому в этом хабратопике я поделюсь техническими решениями, а не инструментами.
Секрет успеха прост:
- хранить документацию так, чтобы с ней можно было удобно и гибко работать;
- автоматизировать всё, что автоматизируемо;
- прикрутить тестирование, непрерывную интеграцию и code review.
Храним так, чтобы было удобно
Мы храним все документы в MS SQL Server и сделали интерфейс (CMS) для простого доступа ко всем документам и их редактирования, проверки и предпросмотра.
Что мы получили:
- Топики — это записи в БД и мы к ним навешали много полезной служебной информации:
- имя автора топика и имя того, кто последним этот топик правил.
- дата создания, дата последнего редактирования, история правок.
- различные статусы: проверен ли корректором, одобрен ли разработчиком, нуждается ли в доработке и т.д.
- Список топиков можно отобразить в виде таблицы со всеми её преимуществами:
- сортировка — можно отсортировать документы в нужном порядке, например, по дате создания.
- группировка — можно группировать документы, например, по статусу, по авторству, и т.д.
- фильтрация — можно показать только те топики, которые требуют внимания, отфильтровав все остальные
- Гибкие возможности представления документов в БД. Вот некоторые из самых вкусных плюшек:
- Локализация. В БД можно удобно организовать хранение и доступ к локализованной документации. Чтобы контролировать процесс локализации, навесьте на топики различные статусы: переведено, не переведено, проверено и т.д. Мы, правда, документацию не локализуем.
- Структура API. В БД можно запросто организовать диаграмму классов, иерархию наследования и т.д. Эту информацию можно использовать для генерации связанных между собой документов.
- Технология единого источника. Если один и тот же контент (картинку, пример кода, текст) надо использовать в нескольких местах, то этот контент можно хранить как отдельную сущность и ссылаться на него там, где он нужен. С БД это делается просто.
Автоматизируй это!
Автогенерация документов из собранных библиотек.
Есть замечательные инструменты, которые позволяют преобразовать документационные комментарии в коде в готовые топики. Это JSDoc, JavaDoc, Doxygen, Sandcastle, тысячи их…
У нас API описывают технические писатели в БД, а не разработчики в коде. Поэтому нам не надо создавать готовые топики из комментариев в исходниках. Нам надо создавать пустые топики в БД.
Эту задачу выполняет специальный инструмент — синхронизатор. Работает он так:
- берёт собранные DLL-ки, через reflection вытаскивает сигнатуры всех пространств имён, классов и т.д.
- сверяет сигнатуры с теми, что есть в БД.
- добавляет недостающее, удаляет лишнее: например, если у класса появился новый метод, то синхронизатор добавляет пустой топик для этого метода в БД с соответствующими статусами.
Технический писатель в интерфейсе к БД отфильтровывает все топики кроме пустых и описывает свежедобавленные классы, методы, свойства и т.д.
Автоматическое заполнение контента там, где это возможно.
Синхронизатор создаёт пустой топик для нового элемента API, и заполняет всю сопутствующую информацию. Возьмём, к примеру, вот этот документ: ASPxGridView.StartRowEditing Event.
Жёлтым маркером я выделил информацию, которую заполняет техписатель непосредственно для этого топика. Особо выделил раздел с примером кода (оранжевым): на него надо дать ссылку в соответствующем поле. Всё содержимое примера должным образом затянется в документ.
Остальное же генерируется автоматически:
- Пространство имён текущего класса и библиотека, в которой этот класс лежит, ставятся автоматом.
- Синтаксис объявления на C# и VB.NET составляется автоматически из служебной информации.
- Дополнительная информация про событие так же вытаскивается автоматически.
- Кроме того, автоматически подставляется табличка с публичными свойствами класса, который содержит данные события (event args).
- Как я писал выше, на пример достаточно дать ссылку, всё содержимое примера подтянется само. Кстати, на этот же пример можно сослаться из другого топика.
- Ссылки на соответствующий класс, члены класса и пространство имён генерируются автоматически. Техписатель может добавить ещё несколько ссылок по своему усмотрению.
Некоторые топики, например те, что содержат список членов класса, генерируются полностью автоматически. Вот список членов класса ASPxGridView. Представляете каково было бы поддерживать этот список вручную?
Тестирование, непрерывная интеграция и code review
Мы пишем документы в XML-подобном формате. По сути, документация — это тоже своего рода код. В нём можно ошибиться: не закрыть тег, ввести недопустимые символы и т.д.
Пользователи получают документацию в более человекочитаемых форматах (HTML на сайте, CHM, PDF, MSH), то есть документацию необходимо собрать из исходников. Исправлять ошибки, накопленные за весь период к подготовке релиза — долго и дорого, поэтому документация должна всегда быть собираема и оттестирована.
Мы поступили логичным образом.
- Написали тесты к документации. А почему бы и нет? Можно автоматически проверять синтаксис в заголовках топиков, можно проверять битые ссылки, закрытость всех тегов, наличие плохих слов в тексте или не-ASCII символов (русскую «С» вместо латинской «C»). Тесты гоняются на CI сервере.
- На CI сервере так же ежедневно собирается билд с инсталляцией документации. Если вдруг не собирается, то мы смотрим билд-лог, принимаем меры и запускаем пересборку.
Code reviewСontent review, проще говоря, вычитка и проверка. Проверка есть грамматическая и фактологическая.- Грамматическая. Документацию мы пишем на английском языке, а так как мы, техписатели, не носители английского, то наш текст на грамматику проверяют корректоры, у которых английский язык — это родной язык. Корректоры проверяют документы в той же CMS, в которой техписатели создают документацию.
- Фактологическая. В CMS предусмотрена возможность предпросмотра топика в виде HTML-странички (точно такой же как на сайте). Ссылку на эту страничку можно отправить разработчику, чтобы тот мог прочесть документ и предложить улучшения.
Заключение
В комментариях к хабратопику с радостью отвечу на ваши вопросы. Буду рад похоливарить обсудить различные организационные и технические моменты, касающиеся написания документации, взаимодействия с разработчиками и пользователями.
Автор: DevExpress
