Ворочаем большими объёмами документации

• А как вы поддерживаете справку по API в актуальном состоянии?
• Как можно организовать и хранить локализованные версии?
• Вы проверяете текст на наличие недопустимых символов и на валидность разметки?
• Как организовать проверку (вычитку) топиков?

Эти и другие вопросы я часто слышу от технических писателей на конференциях. Для небольших объёмов документации достаточно вручную пересмотреть документы и обновить/подставить/поправить всё, что нужно. А если объёмы документации выросли?

Наша документация выросла до более чем 154 000 документов ^[1] только по .NET-линейке продуктов, из них около 140 000 документов — это справка по API. Около 8-10 тысяч топиков добавляются каждый мажорный релиз (т.е. дважды в год). В этой статье я расскажу как мы справляемся с такими объёмами.

Здесь я не приведу названия общедоступных инструментов, потому что всё, что мы используем — это самописные приложения и сервисы, которые глубоко интегрированы в нашу инфраструктуру и слабо применимы вне её. Поэтому в этом хабратопике я поделюсь техническими решениями, а не инструментами.

Секрет успеха прост:

• хранить документацию так, чтобы с ней можно было удобно и гибко работать ^[2];
• автоматизировать всё, что автоматизируемо ^[3];
• прикрутить тестирование, непрерывную интеграцию и code review ^[4].

Храним так, чтобы было удобно

Мы храним все документы в MS SQL Server и сделали интерфейс (CMS) для простого доступа ко всем документам и их редактирования, проверки и предпросмотра.
Что мы получили:

1. Топики — это записи в БД и мы к ним навешали много полезной служебной информации:
   • имя автора топика и имя того, кто последним этот топик правил.
   • дата создания, дата последнего редактирования, история правок.
   • различные статусы: проверен ли корректором, одобрен ли разработчиком, нуждается ли в доработке и т.д.
2. Список топиков можно отобразить в виде таблицы со всеми её преимуществами:
   • сортировка — можно отсортировать документы в нужном порядке, например, по дате создания.
   • группировка — можно группировать документы, например, по статусу, по авторству, и т.д.
     
   • фильтрация — можно показать только те топики, которые требуют внимания, отфильтровав все остальные
     
3. Гибкие возможности представления документов в БД. Вот некоторые из самых вкусных плюшек:
   • Локализация. В БД можно удобно организовать хранение и доступ к локализованной документации. Чтобы контролировать процесс локализации, навесьте на топики различные статусы: переведено, не переведено, проверено и т.д. Мы, правда, документацию не локализуем.
   • Структура API. В БД можно запросто организовать диаграмму классов, иерархию наследования и т.д. Эту информацию можно использовать для генерации связанных между собой документов.
4. Технология единого источника. Если один и тот же контент (картинку, пример кода, текст) надо использовать в нескольких местах, то этот контент можно хранить как отдельную сущность и ссылаться на него там, где он нужен. С БД это делается просто.

Автоматизируй это!

Автогенерация документов из собранных библиотек.

Есть замечательные инструменты, которые позволяют преобразовать документационные комментарии в коде в готовые топики. Это JSDoc, JavaDoc, Doxygen, Sandcastle, тысячи их ^[5]…

У нас API описывают технические писатели в БД, а не разработчики в коде. Поэтому нам не надо создавать готовые топики из комментариев в исходниках. Нам надо создавать пустые топики в БД.

Эту задачу выполняет специальный инструмент — синхронизатор. Работает он так:

1. берёт собранные DLL-ки, через reflection ^[6] вытаскивает сигнатуры всех пространств имён, классов и т.д.
2. сверяет сигнатуры с теми, что есть в БД.
3. добавляет недостающее, удаляет лишнее: например, если у класса появился новый метод, то синхронизатор добавляет пустой топик для этого метода в БД с соответствующими статусами.

Технический писатель в интерфейсе к БД отфильтровывает все топики кроме пустых и описывает свежедобавленные классы, методы, свойства и т.д.

Автоматическое заполнение контента там, где это возможно.

Синхронизатор создаёт пустой топик для нового элемента API, и заполняет всю сопутствующую информацию. Возьмём, к примеру, вот этот документ: ASPxGridView.StartRowEditing Event ^[7].

Жёлтым маркером я выделил информацию, которую заполняет техписатель непосредственно для этого топика. Особо выделил раздел с примером кода (оранжевым): на него надо дать ссылку в соответствующем поле. Всё содержимое примера должным образом затянется в документ.

Остальное же генерируется автоматически:

1. Пространство имён текущего класса и библиотека, в которой этот класс лежит, ставятся автоматом.
2. Синтаксис объявления на C# и VB.NET составляется автоматически из служебной информации.
3. Дополнительная информация про событие так же вытаскивается автоматически.
4. Кроме того, автоматически подставляется табличка с публичными свойствами класса, который содержит данные события (event args).
5. Как я писал выше, на пример достаточно дать ссылку, всё содержимое примера подтянется само. Кстати, на этот же пример можно сослаться из другого топика.
6. Ссылки на соответствующий класс, члены класса и пространство имён генерируются автоматически. Техписатель может добавить ещё несколько ссылок по своему усмотрению.

Некоторые топики, например те, что содержат список членов класса, генерируются полностью автоматически. Вот список членов класса ASPxGridView ^[8]. Представляете каково было бы поддерживать этот список вручную?

Тестирование, непрерывная интеграция и code review

Мы пишем документы в XML-подобном формате. По сути, документация — это тоже своего рода код. В нём можно ошибиться: не закрыть тег, ввести недопустимые символы и т.д.

Пользователи получают документацию в более человекочитаемых форматах (HTML на сайте, CHM, PDF, MSH), то есть документацию необходимо собрать из исходников. Исправлять ошибки, накопленные за весь период к подготовке релиза — долго и дорого, поэтому документация должна всегда быть собираема и оттестирована.

Мы поступили логичным образом.

1. Написали тесты к документации. А почему бы и нет? Можно автоматически проверять синтаксис в заголовках топиков, можно проверять битые ссылки, закрытость всех тегов, наличие плохих слов в тексте или не-ASCII символов (русскую «С» вместо латинской «C»). Тесты гоняются на CI сервере.
   
2. На CI сервере так же ежедневно собирается билд с инсталляцией документации. Если вдруг не собирается, то мы смотрим билд-лог, принимаем меры и запускаем пересборку.
3. Code reviewСontent review, проще говоря, вычитка и проверка. Проверка есть грамматическая и фактологическая.
   • Грамматическая. Документацию мы пишем на английском языке, а так как мы, техписатели, не носители английского, то наш текст на грамматику проверяют корректоры, у которых английский язык — это родной язык. Корректоры проверяют документы в той же CMS, в которой техписатели создают документацию.
   • Фактологическая. В CMS предусмотрена возможность предпросмотра топика в виде HTML-странички (точно такой же как на сайте). Ссылку на эту страничку можно отправить разработчику, чтобы тот мог прочесть документ и предложить улучшения.

Заключение

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

Автор: DevExpress

Источник ^[9]