- А как вы поддерживаете справку по 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-странички (точно такой же как на сайте). Ссылку на эту страничку можно отправить разработчику, чтобы тот мог прочесть документ и предложить улучшения.
Заключение
В комментариях к хабратопику с радостью отвечу на ваши вопросы. Буду рад
Комментарии (17)
IvaYan
03.08.2016 17:09+1Выглядит впечатляюще. Я правильно понял, что топики лежат в одной таблице, независимо от того, что они описывают (класс, поле, метод)?
lexkazakov
03.08.2016 17:17+4Я про это не рассказывал, но уточню.
В одной таблице в CMS показываются топики про один тип элементов. Например, только классы. Или только члены классов (поля, свойства, методы, события и т.д.).
В БД каждый тип элементов представлен несколькими связанными таблицами. Там структура сильно сложнее. Например, статус топика — это отдельная сущность, все статусы хранятся в отдельной таблице. Так же обстоит дело с историей правок.
Impet
03.08.2016 17:21+1А как Ваш синхронизатор работает с Delphi VCL компонентами?
lexkazakov
03.08.2016 17:26+3Эта система используется только для работы с .NET продуктами. Для VCL коллеги используют другие инструменты.
o4karek
03.08.2016 17:27+11. Документация версионируется? Если «да» — как решается проблема изменения в младших версиях для старших?
2. Дока пишется только по исходникам или есть какие-то основополагающие документы?
3. В какие форматы выгружается документация?lexkazakov
03.08.2016 17:42+41. Версионируется. На уровне БД. Для новой версии отсаживаем БД c соответствующим названием. Если надо поправить старую версию, техпис подключается к соответствующей БД, вносит там правки. Может тут же пнуть сборку и через несколько минут получить в нужном формате обновлённую доку.
2. Документацию техписатель пишет основываясь на
— личном опыте (кладёт новый контрол на формочку и разбирается в нём),
— на инфе от разработчиков
— на инфе из технического задания для конпонента или его фичи
— исходниках.
3. Публикуем онлайн (последняя версия), публикуем для скачивания PDF и CHM файлы, инсталляцию MSH-файлов (интегрируются в студийный HelpViewer) и XML-файлики, которые лежат рядом с DLL-ками и обеспечивают наличие подсказок в студийном Intellisence. Xml-файлики для IntelliSence поставляются вместе с самими DLL-ками, отдельно не публикуются.o4karek
03.08.2016 17:47+21. Т.е. не выдается никакой информации о том, что в следующей версии(-ях) надо бы исправленный раздел поправить?
2. Есть какие-то ссылки из записи о топике документации к внешним документам или техпис просто помнит о том, что и где описано?
3. Понятно. Выгрузки сами делали?lexkazakov
03.08.2016 18:12+41. В обычном режиме мы работаем с текущей версией документации. Если надо поправить текст в прошлой версии (и наверняка в нынешней) — приходится копипастить этот текст в две базы.
2. Обычно техпис помнит о том, что ему надо сделать. Тут у каждого свой подход. Я себе карточки в трелло со всеми ссылками и копипастой с писем накидываю, а кто-то может себе наклейки на монитор цеплять, кому как больше нравится.
3. Сборка готового хелпа — самописная. Но вот PDF мы генерируем из CHM сторонним инструментом.o4karek
04.08.2016 09:30+1Понятно. Спасибо!
А какой объем документации (в обычных страничках, например А4, хотя-бы примерно? И сколько народу над этим работает?
SerP1983
03.08.2016 19:18+2А кто заполняет Example? Хранится ли он в CMS? Как техписатель узнает, что уже есть нужный Example.
lexkazakov
03.08.2016 19:24+3Example (пример) пишет техписатель. Может написать по-новой или вытащить готовый из базы знаний.
Примеры тоже хранятся в БД, их там можно создать, удалить, отредактировать из CMS.
Примеры имеют осмысленные названия, можно воспользоваться поиском, чтобы найти нужный пример в базе знаний или в CMS.
77vlad
04.08.2016 10:12+1Вот уж, что хреновое в devexpress так это документация! Отличный механизм чего уж там… Но сама документация отстой
lexkazakov
04.08.2016 10:23+4Спасибо за отзыв.
Будем рады, если вы приведёте конкретные примеры того, где у нас сделано плохо. Если отсутствие какой-либо информации в документации не даёт вам сделать свою работу — напишите нам в техподдержку. Таким образом и вы свою проблему решите, и мы поймём где у нас есть потенциал для улучшения.
Если вам не нравится документация в целом, то приведите примеры хорошей документации
may-cat
Сколько времени ушло на создание, внедрение и допилку системы?
lexkazakov
Систему разработали давно, в начале нулевых. Старожилы говорят, что ведущие разработчики «за пару недель» (с) выкатили.
Допиливать приходилось по-мелочи. Кода не очень много, разобраться и расширить — реально.
Но поддерживать старый код — не очень приятное занятие. Сейчас переписываем морду к базе (упомянутую в топике CMS).