Как документируют ПО?

В этой заметке обозначены самые основные идеи по документированию ПО, информация о том, какая бывает справка и какие подходы применяются к ее созданию.

Виды справки

Справка может быть контекстной или статической. Контекстная справка вызывается по нажатию клавиши F1 в приложении и автоматически открывает страницу с нужной информацией. Статическая справка – это просто документ, в котором последовательно изложена информация о продукте или API-функции. Справку по коду программы, структуры классов и описание их членов можно генерировать «изнутри» (из комментариев внутри кода), а можно «снаружи» (по отдельным описаниям функций и классов в формате XML, HTML, wiki markup).

По принципу единого источника

Часто бывает так, что требуется генерировать сразу несколько форматов справки:

  • Онлайн-справка для посетителей сайта
  • Контекстная справка внутри программы
  • Печатная документация

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

Для этого существует разные XML CMS и XML-схемы (DITA, DocBook), которые позволяют создавать, хранить и управлять XML-документами, из которых генерируется справка сразу нескольких форматов (разработаны соответствующие XSL-преобразования). Однако такие XML CMS довольно дороги, а XML-схема по умолчанию обеспечивает около 80% функциональности, требуемой техническому писателю для создания полноценной документации.

Вот некоторые XML CMS, которые можно использовать для ведения профессиональной документации, каждая из которых стоит порядка 10 – 100 тыс. долларов:

Horizon (http://www.inmedius.com)
XDocs (http://www.bluestream.com/products/xdocs10)
X-Hive/Docato, (http://www.x-hive.com/products/docato/index.html)
TEXTML Server (DITA CMS Framework) (http://www.ixiasoft.com)
Contenta (http://www.xyenterprise.com/)
SiberSafe (http://www.siberlogic.com/)

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

Справка в формате базы знаний

Понятие справки о программе, функции постоянно расширяется. Сейчас уже актуальнее становится не просто молчаливая, пассивная справка, а страница с описанием фичи и с активными комментариями к ней, обменом опыта между пользователями, кто испытывал эту фичу. Документация становится живой, постоянно актуальной и непрерывно улучшаемой благодаря обратной связи с пользователем. Документ обеспечивает не только пассивное описание фичи, но и техническую поддержку продукта. «Последний писк» документирования ПО – использование мощных wiki-систем. Они обеспечивают:

  • Генерацию документов по принципу единого источника из текста, хранящегося в wiki-системе:
  • Хорошую поддержку ЖЦ документа
  • Поддержание в актуальном состоянии документов
  • Средство сбора обратной связи от пользователей

Одной из самых мощных вики-систем на сегодняшний день является продукт австралийских разработчиков – Atlassian Confluence (http://confluence.atlassian.com/display/DOC/Confluence+Documentation+Home).

Неизбежное зло

  • ГОСТЫ. Ужасные требования к документации для программных систем. Приводят к накоплению большого количества бумаги, где суть переливается из пустого в порожнее. Рекомендуют никуда не годную структуру для описания работы с программным продуктом или системой. Но без них нельзя при разработке корпоративных систем для государственных структур.
  • Компромисс между автоматизацией справки и гибкостью дизайна. Чем лучше автоматизирован процесс документации, тем сложнее изменять структуру справки, менять внешний вид, оформление, настраивать дополнительные возможности отображения.
  • Чем актуальнее справка, чем быстрее она обновляется, тем хуже ее структура. С переменным успехом с этим можно бороться, взяв на вооружение хорошую wiki-систему.

Leave a comment

Filed under документирование ПО, единый источник документации, software lifecycle, tech writing

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s