- PVSM.RU - https://www.pvsm.ru -
Эти и другие вопросы я часто слышу от технических писателей на конференциях. Для небольших объёмов документации достаточно вручную пересмотреть документы и обновить/подставить/поправить всё, что нужно. А если объёмы документации выросли?
Наша документация выросла до более чем 154 000 документов [1] только по .NET-линейке продуктов, из них около 140 000 документов — это справка по API. Около 8-10 тысяч топиков добавляются каждый мажорный релиз (т.е. дважды в год). В этой статье я расскажу как мы справляемся с такими объёмами.
Здесь я не приведу названия общедоступных инструментов, потому что всё, что мы используем — это самописные приложения и сервисы, которые глубоко интегрированы в нашу инфраструктуру и слабо применимы вне её. Поэтому в этом хабратопике я поделюсь техническими решениями, а не инструментами.
Секрет успеха прост:
Мы храним все документы в MS SQL Server и сделали интерфейс (CMS) для простого доступа ко всем документам и их редактирования, проверки и предпросмотра.
Что мы получили:
Есть замечательные инструменты, которые позволяют преобразовать документационные комментарии в коде в готовые топики. Это JSDoc, JavaDoc, Doxygen, Sandcastle, тысячи их [5]…
У нас API описывают технические писатели в БД, а не разработчики в коде. Поэтому нам не надо создавать готовые топики из комментариев в исходниках. Нам надо создавать пустые топики в БД.
Эту задачу выполняет специальный инструмент — синхронизатор. Работает он так:
Технический писатель в интерфейсе к БД отфильтровывает все топики кроме пустых и описывает свежедобавленные классы, методы, свойства и т.д.
Синхронизатор создаёт пустой топик для нового элемента API, и заполняет всю сопутствующую информацию. Возьмём, к примеру, вот этот документ: ASPxGridView.StartRowEditing Event [7].
Жёлтым маркером я выделил информацию, которую заполняет техписатель непосредственно для этого топика. Особо выделил раздел с примером кода (оранжевым): на него надо дать ссылку в соответствующем поле. Всё содержимое примера должным образом затянется в документ.
Остальное же генерируется автоматически:
Некоторые топики, например те, что содержат список членов класса, генерируются полностью автоматически. Вот список членов класса ASPxGridView [8]. Представляете каково было бы поддерживать этот список вручную?
Мы пишем документы в XML-подобном формате. По сути, документация — это тоже своего рода код. В нём можно ошибиться: не закрыть тег, ввести недопустимые символы и т.д.
Пользователи получают документацию в более человекочитаемых форматах (HTML на сайте, CHM, PDF, MSH), то есть документацию необходимо собрать из исходников. Исправлять ошибки, накопленные за весь период к подготовке релиза — долго и дорого, поэтому документация должна всегда быть собираема и оттестирована.
Мы поступили логичным образом.
В комментариях к хабратопику с радостью отвечу на ваши вопросы. Буду рад похоливарить обсудить различные организационные и технические моменты, касающиеся написания документации, взаимодействия с разработчиками и пользователями.
Автор: DevExpress
Источник [9]
Сайт-источник PVSM.RU: https://www.pvsm.ru
Путь до страницы источника: https://www.pvsm.ru/net/166553
Ссылки в тексте:
[1] более чем 154 000 документов: https://www.devexpress.com/Support/Documentation/
[2] хранить документацию так, чтобы с ней можно было удобно и гибко работать: #storing
[3] автоматизировать всё, что автоматизируемо: #automation
[4] прикрутить тестирование, непрерывную интеграцию и code review: #agile
[5] тысячи их: https://en.wikipedia.org/wiki/Comparison_of_documentation_generators
[6] reflection: https://msdn.microsoft.com/en-us/library/f7ykdhsy(v=vs.110).aspx
[7] ASPxGridView.StartRowEditing Event: https://documentation.devexpress.com/#AspNet/DevExpressWebASPxGridView_StartRowEditingtopic
[8] список членов класса ASPxGridView: https://documentation.devexpress.com/#AspNet/DevExpressWebASPxGridViewMembersTopicAll
[9] Источник: https://habrahabr.ru/post/306960/?utm_source=habrahabr&utm_medium=rss&utm_campaign=best
Нажмите здесь для печати.